Development Core Setting

From Cloudrexx Development Wiki
Jump to: navigation, search

Introduction

The Setting class contains (mostly static) methods which make it easier to handle settings for all imaginable intentions. The intention is to use this class as a gateway everywhere in Cloudrexx where the user can make configurations via database or file system.

Since Contrexx version 5, there's a database, file system and Yaml storage engine available.

Note: Before trying to access a component's settings, DON'T forget to call {@see \Cx\Core\Setting\Controller\Setting::init()} before calling getValue() for the first time!

Documentation

Contrexx API Cx\Core\Setting class

Note: For Contrexx versions below 5.0 see article SettingDb

Global Configuration

The Global Configuration section (Administration > Global Configuration > System) does use this library to store and manage its configuration options. As a special extension to the Setting library, the configuration options of the Global Configuration are shadowed into the environment variable $_CONFIG. This is used to make the Global Configuration options available in a very early stage of the bootstrapping process.

The Setting library is not available until the postInit-hook. To overcome this issue, the Global Configuration options are accessible through the environment variable $_CONFIG in earlier stages.

However, from the postInit-hook onwards you must always use the Setting library to access the Global Configuration options. Accessing the Global Configuration options through the environment variable $_CONFIG after the postComponentLoad-hook (which is the predecessor of postInit) is regarded as deprecated code.

Methods

  • static function changed()
    • TRUE, if minimum one of the loaded setting has been changed (updateAll() will check these)
    • \Cx\Core\Setting\Controller\Setting::changed()
  • static function tab_index($tab_index=null)
    • Get or set the current tab
    • \Cx\Core\Setting\Controller\Setting::tab_index(integer $tab_index)
  • static function init($section, $group = null, $engine = 'Database', $fileSystemConfigRepository = null, $populate = 0)
    • Activate or load the setting for a specific module (as the case may be constricted on a given group)
    • Section must be set up
    • The Engine type Database or File system, Default to set Database, You may use engine type FileSystem
    • Database engine: \Cx\Core\Setting\Controller\Setting::init($section, $group,$engine = 'Database')
    • FileSystem engine: \Cx\Core\Setting\Controller\Setting::init($section, $group,$engine = 'FileSystem')
    • Yaml engine: \Cx\Core\Setting\Controller\Setting::init($section, $group,$engine = 'Yaml')
    • Once you initialize section, it is stored in global Setting array and you don't not need to reinitialize it, unless other specified.
    • You may set behavior of what to do when section already exists with $populate:
      • \Cx\Core\Setting\Controller\Setting::NOT_POPULATE - do nothing, return; default behavior
      • \Cx\Core\Setting\Controller\Setting::POPULATE - add values to existing array
      • \Cx\Core\Setting\Controller\Setting::REPOPULATE - reload section; default behavior in old logic
      • Example: \Cx\Core\Setting\Controller\Setting::init($section, $group, $engine, null, \Cx\Core\Setting\Controller\Setting::POPULATE)
  • static function flush()
    • Reset the content of the class (forces for example the re-initialization at the next getArray())
    • \Cx\Core\Setting\Controller\Setting::flush()
  • static function getArray($section = null, $group=null)
    • Returns array of current engine based on $section and $group.
    • If no section is specified, currently set section is taken into consideration.
  • static function getValue($name, $section = null)
    • Returns the value for the setting with the given name
    • If $section is specified, loads value from $section, otherwise loads value from currently set section
    • \Cx\Core\Setting\Controller\Setting::getValue($name, $section)
  • static function set($name, $value)
    • Set the value of the setting with the given name
    • \Cx\Core\Setting\Controller\Setting::set($name,$value)
  • static function updateAll()
    • Stores the loaded settings into the database or FileSystem\Yaml (only if minimum one change have been done)
    • \Cx\Core\Setting\Controller\Setting::updateAll()
  • static function update($name)
    • Stores one setting (without check!)
    • Updates the value for the given name in the settings,note that this method does not work for adding new settings.
    • \Cx\Core\Setting\Controller\Setting::update($name)
  • static function add($name, $value, $ord=false, $type='text', $values=, $group=null)
    • Adds a new setting to the group
    • This method is only used for an installation script for a new module or will be used in update.
    • \Cx\Core\Setting\Controller\Setting::add( $name, $value, $ord, $type, $values,$group)
  • static function storeFromPost()
    • Update and store all settings found in the post array
    • \Cx\Core\Setting\Controller\Setting::storeFromPost()
  • static function delete($name=null, $group=null)
    • Deletes the setting with the given name. Only for advanced users!
    • Delete one or more records from the Database or FileSystem
    • At least one of the parameter values must be non-empty.
    • \Cx\Core\Setting\Controller\Setting::delete($name, $group)
  • static function show(&$objTemplateLocal, $uriBase, $section=, $tab_name=, $prefix='TXT_')
    • Shows the settings in the given template object
    • \Cx\Core\Setting\Controller\Setting::show($objTemplate, $uriBase, $section, $tab_name, $prefix)
  • static function show_section(&$objTemplateLocal, $section=, $prefix='TXT_')
    • Shows the settings for the given group in the given template object
    • \Cx\Core\Setting\Controller\Setting::show_section($objTemplate, $section, $prefix)
  • static function show_external(&$objTemplateLocal, $tab_name, $content)
    • Includes an external site (e.g. MailTemplates) into the Setting view (as a new tab)
    • Adds an external settings view to the current template
    • \Cx\Core\Setting\Controller\Setting::show_external($objTemplate, $tab_name, $content)
  • static function storeFromPost()
    • Stores POST data and saves it to Database\FileSystem\Yaml using set() and updateAll().
    • Should always be used to store POST data.
    • \Cx\Core\Setting\Controller\Setting::storeFromPost()
  • static function getSectionEngine($section = null, $engine = null)
    • Returns engine of section.
    • If no section specified takes currenty set section.
    • If section don't exist throws exception.
    • If $engine don't exist takes default engine of section.
    • \Cx\Core\Setting\Controller\Setting::getSectionEngine($section, $engine)
  • static function getSectionEngine($section = null, $engine = null)
    • Returns engine of section.
    • If no section specified takes currenty set section.
    • If section don't exist throws exception.
    • If $engine don't exist takes default engine of section.
    • \Cx\Core\Setting\Controller\Setting::getSectionEngine($section, $engine)
  • static function setSectionEngine($oSectionEngine, $populate)
    • Sets engine for section. Uses by init() but can also be called separately;
    • If engine of section already exists - acts depending of $populate behavior:
      • \Cx\Core\Setting\Controller\Setting::NOT_POPULATE - do nothing, return; default behavior
      • \Cx\Core\Setting\Controller\Setting::POPULATE - add values to existing array
      • \Cx\Core\Setting\Controller\Setting::REPOPULATE - reload section; default behavior in old logic
    • \Cx\Core\Setting\Controller\Setting::setSectionEngine($oSectionEngine, $populate)
  • static function setEngineType($section, $engine, $group = null)
    • Sets current section, engine and group;
    • Once all data is initialized, should be used instead of init(); in case you want to get specific section\engine\group (i.e. in tabs)!
    • \Cx\Core\Setting\Controller\Setting::setEngineType($section, $engine, $group)
  • static function addToArray($name, $value)
    • Adds an element to array.
    • Current section and engine are taken into consideration.
    • \Cx\Core\Setting\Controller\Setting::addToArray($name, $value)
  • static function getSettings($section = null, $engine = null, $group = null)
    • Basic method to get data array easy based of section, engine and group. Recommended to use!
    • If section is null returns whole multidimensional array of all engines and sections.
    • If section is set returns multidimensional array of all engines of that section.
    • If section and engine is set returns data array from that section and engine.
    • If section, engine and group are specified returns elements of concrete group from section and engine array.
    • \Cx\Core\Setting\Controller\Setting::getSettings($section = null, $engine = null, $group = null)
  • static function getCurrentSettings()
    • Returns data array based on currently set section, engine and group.
    • Current section, engine and group can be set up via \Cx\Core\Setting\Controller\Setting::setEngineType($section, $engine, $group)
    • Recommended to use in most of cases (i.e. in storeFromPost or other functions that work with data arrays).
    • \Cx\Core\Setting\Controller\Setting::getCurrentSettings()

Engines

Engine Description
Database (default) Stores the configuration options in the database (table contrexx_core_setting)
FileSystem Stores the configuration options in the filesystem in plain YAML notation (in config/<section>.yml)
Yaml Stores the configuration options as serialized objects in the filesystem in YAML notation (in config/<section>.yml)

Examples

Initialization

Initialization of the configuration options is required, otherwise no operation will work

Database engine
// initializing the configuration options of group 'config' from section 'Shop'
\Cx\Core\Setting\Controller\Setting::init('Shop', 'config');

// identical as the call above
\Cx\Core\Setting\Controller\Setting::init('Shop', 'config', 'Database');
FileSystem engine
// initializing the configuration options of group 'config' from section 'MultiSite'
\Cx\Core\Setting\Controller\Setting::init('MultiSite', 'config','FileSystem');
Yaml engine
// initializing the configuration options of all groups from section 'Config'
\Cx\Core\Setting\Controller\Setting::init('Config', '','Yaml');


Array populating options

If section is already initialized, we can define behavior of populating this section with data. For that purpose we have 5th parameter. Assuming we have already initialized section Config\Yaml and have following data in it`s array: array(1,2), and by calling init of this section we would retrieve array(2,3,4). Then:

NOT_PUPULATE (default)
// would check if section exists and returns, doing no action; We still have array(1,2)
\Cx\Core\Setting\Controller\Setting::init('Config', '','Yaml', null, Setting::NOT_PUPULATE);
POPULATE
// would retrieve elements from Yaml and add elements that not exist to array; In the end we will have array(1,2,3,4)
\Cx\Core\Setting\Controller\Setting::init('Config', '','Yaml', null, Setting::NOT_PUPULATE);
REPOPULATE
// would replace array with new data;  In the end we will have array(2,3,4);
\Cx\Core\Setting\Controller\Setting::init('Config', '', 'Yaml', null, Setting::REPOPULATE);

Switching section, engine, module

There are several ways to switch between section and engine once initialized.

By calling setEngineType (Recommended)
// initialize section
\Cx\Core\Setting\Controller\Setting::init('Config', '','Yaml');

//would switch to the section MultiSite, engine FileSystem and group config; If engine not exists - returns false;
\Cx\Core\Setting\Controller\Setting::setEngineType('MultiSite', 'FileSystem', 'config');
By calling init()
// initialize section
\Cx\Core\Setting\Controller\Setting::init('Config', '','Yaml');

//would switch to the section MultiSite, engine FileSystem and group config; if section not exists - would initialize it
\Cx\Core\Setting\Controller\Setting::init('MultiSite', 'config','FileSystem');

Fetching data

Once the configuration data has been initialized (see \Cx\Core\Setting\Controller\Setting::init() above) it can be accessed as follows:

// initialize section
\Cx\Core\Setting\Controller\Setting::init('MultiSite', 'config', 'FileSystem');

// fetch data
$mode = \Cx\Core\Setting\Controller\Setting::getValue('mode');

// fetch data from section Config
$mode = \Cx\Core\Setting\Controller\Setting::getValue('mode', 'Config');

To fetch array of data, following methods can be called:

getSettings() (Recommended)
// fetch complete array from all sections and engines; Each section engine is an object; 
$data = \Cx\Core\Setting\Controller\Setting::getSettings();
// fetch data from section engine object
$sectionData = $data['MultiSite']['FileSystem']->getArraySettings();

// fetch all engines of section MultiSite';
$data = \Cx\Core\Setting\Controller\Setting::getSettings('MultiSite');
// fetch data from section engine object
$sectionData = $data['FileSystem']->getArraySettings();

// fetch data from section 'MultiSite' and engine 'Database';
$data = \Cx\Core\Setting\Controller\Setting::getSettings('MultiSite', 'Database');

// fetch data from section 'MultiSite', engine 'Database' and group 'config';
$data = \Cx\Core\Setting\Controller\Setting::getSettings('MultiSite', 'Database', 'Config');
getArray()
// initialize section
\Cx\Core\Setting\Controller\Setting::init('MultiSite', '', 'FileSystem');

// fetch data from section MultiSite 
$mode = \Cx\Core\Setting\Controller\Setting::getArray();

// fetch data from section Config, group confing
$mode = \Cx\Core\Setting\Controller\Setting::getArray('Config');

// fetch data from section Config, group core
$mode = \Cx\Core\Setting\Controller\Setting::getArray('Config','core');


Add new configuration option

Basic example
// initialize section
\Cx\Core\Setting\Controller\Setting::init('MultiSite', 'config', 'FileSystem');

// add new configuration option 'simpleTextOption'
\Cx\Core\Setting\Controller\Setting::add('simpleTextOption', 'defaultText', 1, \Cx\Core\Setting\Controller\Setting::TYPE_TEXT, null, 'config')
Advanced example

Add new configuration option only if it does not yet exist and throw exception in case the operation fails.

// initialize section
\Cx\Core\Setting\Controller\Setting::init('MultiSite', 'config', 'FileSystem');

// add new configuration option, if it does not yet exist
if (!\Cx\Core\Setting\Controller\Setting::isDefined('simpleTextOption')
    && !\Cx\Core\Setting\Controller\Setting::add('simpleTextOption', 'defaultText', 1, \Cx\Core\Setting\Controller\Setting::TYPE_TEXT, null, 'config')
){
    throw new \Exception("Failed to add new configuration option");
}

Display configuration options

Display configuration options using auto generated view
// initialize section
\Cx\Core\Setting\Controller\Setting::init('MultiSite', 'config', 'FileSystem');

// auto generate html form to modify all configuration options from the loaded section
\Cx\Core\Setting\Controller\Setting::show(
    $objTemplate,
    'index.php?cmd=MultiSite&act=settings',
    'MultiSite',
    'General',
    'TXT_CORE_MODULE_MULTISITE_'
);
Advanced example by integrating external MailTemplate view
// initialize section
\Cx\Core\Setting\Controller\Setting::init('Shop', 'config');

// show external generated view of MailTemplate
$objTemplate = new \Cx\Core\Html\Sigma('/path/to/html/template');
\Cx\Core\Setting\Controller\Setting::show_external(
    $objTemplate,
    'Mail Templates',
    \MailTemplate::overview('shop', 'config', \Cx\Core\Setting\Controller\Setting::getValue('numof_mailtemplate_per_page_backend'))->get()
);
\Cx\Core\Setting\Controller\Setting::show_external(
    $objTemplate,
    'Manage Mail Template',
    \MailTemplate::edit('shop')->get()
);

// TODO: instead of using echo, do assign the returned string to a template variable 
echo $objTemplate->get();

Update configuration option

Automatically store all options from POST-data (from auto-generated view)
// initialize section
\Cx\Core\Setting\Controller\Setting::init('MultiSite', null, 'FileSystem');  

// update options from POST-data (if set)
if (isset($_POST) && !empty($_POST['bsubmit'])) {
    \Cx\Core\Setting\Controller\Setting::storeFromPost();
}
Update single configuration option
// initialize section
\Cx\Core\Setting\Controller\Setting::init('MultiSite', null, 'FileSystem');

// set new value to configuration option
\Cx\Core\Setting\Controller\Setting::set('email', $email);

// store changed configuration option
if (\Cx\Core\Setting\Controller\Setting::update('email')) {
    echo 'Config successfully updated';
}
Update multiple configuration options
// initialize section
\Cx\Core\Setting\Controller\Setting::init('MultiSite', null, 'FileSystem');

// set new values to configuration options
\Cx\Core\Setting\Controller\Setting::set('email', $email);
\Cx\Core\Setting\Controller\Setting::set('address', $address);
\Cx\Core\Setting\Controller\Setting::set('user', $user);

// store all changed configuration options
if (\Cx\Core\Setting\Controller\Setting::updateAll() === true) { // updateAll() returns NULL on a no-op
    echo 'Config successfully updated';
}