Class: UserSettingsManager

Class for management of the user settings.

Details

When you introduce a new user setting. You have to create a column for it in the corresponding table add it to the initialization and specify the data type.

The user settings are loaded only once by the start of the session and are kept until the session is valid. Saving of the user settings updates both the session and the database. When a settings are requested, it is taken from the session, not from the database.

Implements

\SmartFactory\Interfaces\ISettingsManager

Authors

Oleg Schildt

Package

System

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\ConfigSettingsManager
\SmartFactory\RuntimeSettingsManager

Uses

\SmartFactory\DatabaseWorkers\DBWorker

 

Properties
protected

Internal variable for storing the current context.
protected

Internal variable for storing the dbworker.
protected

Internal array for storing the auxiliary tables for storing the multichoce values.
protected

Internal variable for storing the state whether the translation should be started or commited or no transaction should be used because the saving process is a part of other saving process.
protected

Internal variable for storing the array of the settings values.
protected

Internal array for storing the settings tables.
protected

Internal variable for storing the user id.
protected

Internal variable for storing the validator.
Methods
public

Returns the current settings context.
public

Returns the value of a settings parameter.
public

Gets the user id to be used for loading settings.
public

Returns the validator for the settings.
public

Initializes the settings manager parameters.
public

Loads the settings from the target user table.
protected

This is internal auxiliary function for loading the settings from the target user table defined by the initialization.
public

Saves the settings from to the target user table.
protected

This is internal auxiliary function for storing the settings to the target user table defined by the initialization.
public

Sets the settings context.
public

Sets the dbworker to use for loading and storing settings.
public

Sets a settings parameter.
public

Sets settings parameters from an array.
public

Sets the user id to be used for loading settings.
public

Sets the validator for the settings.
protected

This is internal auxiliary function for checking that the settings manager is intialized correctly.
public

Validates the current settings values.

Property: UserSettingsManager::$context

protected string $context = "default";

Internal variable for storing the current context.

Type

string

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::getContext()
\SmartFactory\UserSettingsManager::setContext()

Property: UserSettingsManager::$dbworker

protected ?\DatabaseWorkers\DBWorker $dbworker;

Internal variable for storing the dbworker.

Type

?\DatabaseWorkers\DBWorker

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

Property: UserSettingsManager::$multichoice_tables

protected array $multichoice_tables = [];

Internal array for storing the auxiliary tables for storing the multichoce values.

Type

array

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

Property: UserSettingsManager::$no_own_transaction

protected bool $no_own_transaction = true;

Internal variable for storing the state whether the translation should be started or commited or no transaction should be used because the saving process is a part of other saving process.

Type

bool

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

Property: UserSettingsManager::$settings

protected array $settings = [];

Internal variable for storing the array of the settings values.

Type

array

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

Property: UserSettingsManager::$settings_tables

protected array $settings_tables = [];

Internal array for storing the settings tables.

Type

array

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

Property: UserSettingsManager::$user_id

protected string $user_id = "";

Internal variable for storing the user id.

Type

string

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::setUserID()

Property: UserSettingsManager::$validator

protected ?\SmartFactory\Interfaces\ISettingsValidator $validator = null;

Internal variable for storing the validator.

Type

?\SmartFactory\Interfaces\ISettingsValidator

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::getValidator()
\SmartFactory\UserSettingsManager::setValidator()

Method: UserSettingsManager::getContext()

public function getContext(): string;

Returns the current settings context.

Details

Settings might be edited not in one dialog, There can be several masks for different type of settings, or the settings can be configured in a wizard. In this case, only a subset of settings has to be saved and validated. To be able to write a flexible validator for the subsets, the $context is used. It can be - step1, step1, server_settings, db_connection_settings etc.

Returns

string

Returns the current settings context.

Overrides

\SmartFactory\Interfaces\ISettingsManager::getContext()

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::setContext()

Method: UserSettingsManager::getParameter()

public function getParameter(string $name, mixed|null $default = null): mixed;

Returns the value of a settings parameter.

Parameters

Name Pass type Value type Default value Description
$name by value string

The name of the settings parameter.
$default by value mixed|null null

The default value of the settings parameter if it is not set yet. The parameter is a conformable way to pre-set a parameter to a default value if its value is not set yet.

Returns

mixed

Returns the value of the settings parameter.

Throws

\Exception

It might throw an exception in the case of any errors:

  • if some parameters are missing.
  • if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
  • if some parameters are not of the proper type.
  • if the query fails or if some object names are invalid.

Overrides

\SmartFactory\Interfaces\ISettingsManager::getParameter()

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::setParameter()
\SmartFactory\UserSettingsManager::setParameters()

Method: UserSettingsManager::getUserID()

public function getUserID(): int|string|null;

Gets the user id to be used for loading settings.

Returns

int|string|null

Returns the user id or null if not set.

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::setUserID()

Method: UserSettingsManager::getValidator()

public function getValidator(): ?\SmartFactory\Interfaces\ISettingsValidator;

Returns the validator for the settings.

Returns

?\SmartFactory\Interfaces\ISettingsValidator

Returns the validator for the settings or null if none is defined.

Overrides

\SmartFactory\Interfaces\ISettingsManager::getValidator()

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::setValidator()
\SmartFactory\UserSettingsManager::validateSettings()

Method: UserSettingsManager::init()

public function init(array $parameters): void;

Initializes the settings manager parameters.

Parameters

Name Pass type Value type Default value Description
$parameters by value array

Settings for saving and loading as an associative array in the form key => value:

  • $parameters["dbworker"] - the dbworker to use for loading and storing settings.
  • $parameters["settings_tables"] - the definitions of the settings tables.
  • $parameters["multichoice_tables"] - the definitions of the auxiliary tables for the multichoice values.

Example:

  $instance->init([
          "dbworker" => app_dbworker(),

          "settings_tables" => [
               "users" => [
                   "id" => DBWorker::DB_NUMBER,
                   "language" => DBWorker::DB_STRING,
                   "time_zone" => DBWorker::DB_STRING
               ],
               "user_forum_settings" => [
                   "user_id" => DBWorker::DB_NUMBER,
                   "signature" => DBWorker::DB_STRING,
                   "status" => DBWorker::DB_STRING,
                   "hide_pictures" => DBWorker::DB_NUMBER,
                   "hide_signatures" => DBWorker::DB_NUMBER
               ]
          ],

          "multichoice_tables" => [
               "user_colors" => [
                   "user_id" => DBWorker::DB_NUMBER,
                   "color" => DBWorker::DB_STRING
               ]
          ]
  ]);

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

\Exception

It might throw an exception in the case of any errors.

Overrides

\SmartFactory\Interfaces\ISettingsManager::init()

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

Method: UserSettingsManager::loadSettings()

public function loadSettings(): void;

Loads the settings from the target user table.

Details

The user ID must be set before loading settings, see \SmartFactory\UserSettingsManager::setUserID().

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

  • if some parameters are missing.
  • if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
  • if some parameters are not of the proper type.
  • if the query fails or if some object names are invalid.

Overrides

\SmartFactory\Interfaces\ISettingsManager::loadSettings()

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::saveSettings()

Method: UserSettingsManager::loadSettingsData()

protected function loadSettingsData(array &$data): void;

This is internal auxiliary function for loading the settings from the target user table defined by the initialization.

Parameters

Name Pass type Value type Default value Description
$data by reference array

The target array with the settings values to be loaded.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

  • if the query fails or if some object names are invalid.
  • if some parameters are missing.
  • if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
  • if some parameters are not of the proper type.
  • if the query fails or if some object names are invalid.

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::saveSettingsData()

Method: UserSettingsManager::saveSettings()

public function saveSettings(): void;

Saves the settings from to the target user table.

Returns

void

Throws

\Exception|\Throwable

It might throw an exception in the case of any errors:

  • if some parameters are missing.
  • if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
  • if some parameters are not of the proper type.
  • if the query fails or if some object names are invalid.

Overrides

\SmartFactory\Interfaces\ISettingsManager::saveSettings()

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::loadSettings()

Method: UserSettingsManager::saveSettingsData()

protected function saveSettingsData(array $data): void;

This is internal auxiliary function for storing the settings to the target user table defined by the initialization.

Parameters

Name Pass type Value type Default value Description
$data by value array

The array with the settings values to be saved.

Returns

void

Throws

\Throwable

It might throw an exception in the case of any errors:

  • if the query fails or if some object names are invalid.
  • if some parameters are missing.
  • if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
  • if some parameters are not of the proper type.
  • if the query fails or if some object names are invalid.

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::loadSettingsData()

Method: UserSettingsManager::setContext()

public function setContext(string $context = "default"): void;

Sets the settings context.

Details

Settings might be edited not in one dialog, There can be several masks for different type of settings, or the settings can be configured in a wizard. In this case, only a subset of settings has to be saved and validated. To be able to write a flexible validator for the subsets, the $context is used. It can be - step1, step1, server_settings, db_connection_settings etc.

Parameters

Name Pass type Value type Default value Description
$context by value string "default"

The settings context.

Returns

void

Overrides

\SmartFactory\Interfaces\ISettingsManager::setContext()

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::getContext()

Method: UserSettingsManager::setDBWorker()

public function setDBWorker(\SmartFactory\DatabaseWorkers\DBWorker $dbworker, bool $no_own_transcation = false): void;

Sets the dbworker to use for loading and storing settings.

Parameters

Name Pass type Value type Default value Description
$dbworker by value \SmartFactory\DatabaseWorkers\DBWorker

The dbworker to be used for loading and storing settings.
$no_own_transcation by value bool false

The state whether the translation should be started or commited or no transaction should be used because the saving process is a part of other saving process.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors.

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\RecordsetManager::getDBWorker()

Method: UserSettingsManager::setParameter()

public function setParameter(string $name, mixed $value): void;

Sets a settings parameter.

Parameters

Name Pass type Value type Default value Description
$name by value string

The name of the settings parameter.
$value by value mixed

The value of the settings parameter.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

  • if some parameters are missing.
  • if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
  • if some parameters are not of the proper type.
  • if the query fails or if some object names are invalid.

Overrides

\SmartFactory\Interfaces\ISettingsManager::setParameter()

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::getParameter()
\SmartFactory\UserSettingsManager::setParameters()

Method: UserSettingsManager::setParameters()

public function setParameters(array $parameters, bool $force_creation = false): void;

Sets settings parameters from an array.

Parameters

Name Pass type Value type Default value Description
$parameters by value array

Array of parameters in the form key => value.
$force_creation by value bool false

Flag which defines whether the parameter should be created if not exists. If false, only existing parameters are updated. In the UserSettingsManager, this flag is ignored, because the parameters are mapped to the database fields and cannot be created on the fly.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

  • if some parameters are missing.
  • if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
  • if the query fails or if some object names are invalid.
  • if the config file is not readable.

Overrides

\SmartFactory\Interfaces\ISettingsManager::setParameters()

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::getParameter()
\SmartFactory\UserSettingsManager::setParameter()

Method: UserSettingsManager::setUserID()

public function setUserID(string $user_id): void;

Sets the user id to be used for loading settings.

Details

The user ID must be set before loading settings, see \SmartFactory\UserSettingsManager::loadSettings().

Parameters

Name Pass type Value type Default value Description
$user_id by value string

The user ID.

Returns

void

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::loadSettings()
\SmartFactory\UserSettingsManager::getUserID()

Method: UserSettingsManager::setValidator()

public function setValidator(\SmartFactory\Interfaces\ISettingsValidator $validator): void;

Sets the validator for the settings.

Parameters

Name Pass type Value type Default value Description
$validator by value \SmartFactory\Interfaces\ISettingsValidator

The settings validator.

Returns

void

Overrides

\SmartFactory\Interfaces\ISettingsManager::setValidator()

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::getValidator()
\SmartFactory\UserSettingsManager::validateSettings()

Method: UserSettingsManager::validateParameters()

protected function validateParameters(): void;

This is internal auxiliary function for checking that the settings manager is intialized correctly.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

Method: UserSettingsManager::validateSettings()

public function validateSettings(): void;

Validates the current settings values.

Details

It should be called after settings the new values of the parameters and before their saving.

Returns

void

Throws

\Exception

It might throw exceptions in the case of any errors.

Overrides

\SmartFactory\Interfaces\ISettingsManager::validateSettings()

Authors

Oleg Schildt

Source code

SmartFactory/UserSettingsManager.php

See also

\SmartFactory\UserSettingsManager::getValidator()
\SmartFactory\UserSettingsManager::setValidator()

Uses

\SmartFactory\Interfaces\ISettingsValidator