Documentation

Setting
in package

cloudrexx

core

setting

Manages settings stored in the database or file system

Before trying to access a modules' settings, DON'T forget to call Setting::init() before calling getValue() for the first time!

Constants

NOT_POPULATE = 0: Init behavior mode in case same section engine present (i.e. we called them with different groups): NOT_POPULATE - return; default behavior POPULATE - init and add elements to existing array REPOPULATE - init and replace existing array
POPULATE = 1
REPOPULATE = 2
TYPE_BUTTON = 'button'
TYPE_CHECKBOX = 'checkbox'
TYPE_CHECKBOXGROUP = 'checkboxgroup'
TYPE_DATE = 'date'
TYPE_DATETIME = 'datetime'
TYPE_DROPDOWN = 'dropdown': Setting types See {@see show()} for examples on how to extend these.
TYPE_DROPDOWN_MULTISELECT = 'dropdown_multiselect'
TYPE_DROPDOWN_USER_CUSTOM_ATTRIBUTE = 'dropdown_user_custom_attribute'
TYPE_DROPDOWN_USERGROUP = 'dropdown_usergroup'
TYPE_EMAIL = 'email'
TYPE_FILECONTENT = 'file'
TYPE_FILEUPLOAD = 'fileupload'
TYPE_IMAGE = 'image'
TYPE_PASSWORD = 'password'
TYPE_RADIO = 'radio'
TYPE_TEXT = 'text'
TYPE_TEXTAREA = 'textarea'
TYPE_WYSIWYG = 'wysiwyg'

Properties

$arrSettings : mixed
$currentTablist : int
$engine : mixed
$engines : mixed
$group : mixed
$instanceId : mixed
$section : mixed
$tab_index : mixed
$tablists : array<string|int, mixed>

Methods

__getOldSettings() : array<string|int, mixed>: Returns the settings from the old settings table for the given module ID, if available
add() : bool: Add a new record to the settings
addToArray() : bool: Adds element to array
alter() : bool: Alter an existing setting entry
changed() : bool: Returns the current value of the changed flag.
delete() : bool: Delete one or more records from the database table
deleteModule() : bool: Deletes all entries for the current section
errorHandler() : bool: Should be called whenever there's a problem with the settings table
flush() : void: Flush the stored settings
getArray() : array<string|int, mixed>: Returns the settings array for the given section and group
getCurrentEngine() : type: Returns current Engine name
getCurrentGroup() : type: Returns current group name
getCurrentSection() : string: Returns current Section name
getCurrentSettings() : array<string|int, mixed>|false: Gets current settings based on currently set section, engine and group
getCurrentTablistName() : string: Returns the name of the current tab list
getCurrentTabName() : string: Returns the name of the current tab
getEngineType() : type: Retuns class of the engine
getGroup() : mixed
getInstanceId() : mixed: Returns Id of current instance
getSectionEngine() : type: Returns engine from section
getSettings() : bool: Enhanced method of getting settins by section, engine and group; Recommended for use in future; getArray() is just for backward compatibility
getValue() : mixed: Returns the settings value stored in the section for the name given.
init() : bool: Initialize the settings entries from the database with key/value pairs for the current section and the given group
isDefined() : bool: Returns the true or false, if settings name is exist or not .
joinValues() : string: Joins the strings in the array with commas into a single values string
set() : bool: Updates a setting
setEngineType() : mixed: Set engineType
setGroup() : mixed
setSectionEngine() : mixed: Sets engine of section.
show() : bool: Display the settings present in the $arrSettings class array
show_external() : bool: Adds an external settings view to the current template
show_section() : bool: Display a section of settings present in the $arrSettings class array
splitValues() : array<string|int, mixed>: Splits the string value at commas and returns an array of strings
storeFromPost() : bool: Update and store all settings found in the $_POST array
tab_index() : int: Optionally sets and returns the value of the tab index
update() : bool: Updates the value for the given name in the settings table
updateAll() : bool: Stores all settings entries present in the $arrSettings object array variable
verify_template() : mixed: Ensures that a valid template is available
getValuesFromSelectionAsArray() : array<string|int, mixed>: Get selectable options as array from string definition
isValidInputFromSelection() : bool: Verify that $input is a valid selection of $selection
parseFileSizeValue() : string: Parses value into literal file size notation

NOT_POPULATE

Init behavior mode in case same section engine present (i.e. we called them with different groups): NOT_POPULATE - return; default behavior POPULATE - init and add elements to existing array REPOPULATE - init and replace existing array


    public
        mixed
    NOT_POPULATE
    = 0

POPULATE


    public
        mixed
    POPULATE
    = 1

REPOPULATE


    public
        mixed
    REPOPULATE
    = 2

TYPE_BUTTON


    public
        mixed
    TYPE_BUTTON
    = 'button'

TYPE_CHECKBOX


    public
        mixed
    TYPE_CHECKBOX
    = 'checkbox'

TYPE_CHECKBOXGROUP


    public
        mixed
    TYPE_CHECKBOXGROUP
    = 'checkboxgroup'

TYPE_DATE


    public
        mixed
    TYPE_DATE
    = 'date'

TYPE_DATETIME


    public
        mixed
    TYPE_DATETIME
    = 'datetime'

TYPE_DROPDOWN

Setting types See {@see show()} for examples on how to extend these.


    public
        mixed
    TYPE_DROPDOWN
    = 'dropdown'

TYPE_DROPDOWN_MULTISELECT


    public
        mixed
    TYPE_DROPDOWN_MULTISELECT
    = 'dropdown_multiselect'

TYPE_DROPDOWN_USER_CUSTOM_ATTRIBUTE


    public
        mixed
    TYPE_DROPDOWN_USER_CUSTOM_ATTRIBUTE
    = 'dropdown_user_custom_attribute'

TYPE_DROPDOWN_USERGROUP


    public
        mixed
    TYPE_DROPDOWN_USERGROUP
    = 'dropdown_usergroup'

TYPE_EMAIL


    public
        mixed
    TYPE_EMAIL
    = 'email'

TYPE_FILECONTENT


    public
        mixed
    TYPE_FILECONTENT
    = 'file'

TYPE_FILEUPLOAD


    public
        mixed
    TYPE_FILEUPLOAD
    = 'fileupload'

TYPE_IMAGE


    public
        mixed
    TYPE_IMAGE
    = 'image'

TYPE_PASSWORD


    public
        mixed
    TYPE_PASSWORD
    = 'password'

TYPE_RADIO


    public
        mixed
    TYPE_RADIO
    = 'radio'

TYPE_TEXT


    public
        mixed
    TYPE_TEXT
    = 'text'

TYPE_TEXTAREA


    public
        mixed
    TYPE_TEXTAREA
    = 'textarea'

TYPE_WYSIWYG


    public
        mixed
    TYPE_WYSIWYG
    = 'wysiwyg'

$arrSettings


        public
        static    mixed
    $arrSettings
     = array()

$currentTablist


        protected
        static    int
    $currentTablist
     = 0

$engine


        protected
        static    mixed
    $engine
     = 'Database'

$engines


        protected
        static    mixed
    $engines
     = array('Database' => '\Cx\Core\Setting\Model\Entity\DbEngine', 'FileSystem' => '\Cx\Core\Setting\Model\Entity\FileSystem', 'Yaml' => '\Cx\Core\Setting\Model\Entity\YamlEngine')

$group


        protected
        static    mixed
    $group
     = null

$instanceId


        protected
        static    mixed
    $instanceId
     = null

$section


        protected
        static    mixed
    $section
     = null

$tab_index


        protected
        static    mixed
    $tab_index
     = 1

$tablists


        protected
        static    array<string|int, mixed>
    $tablists
     = array()

__getOldSettings()

Returns the settings from the old settings table for the given module ID, if available


    public
            static        __getOldSettings(int $module_id) : array<string|int, mixed>

If the module ID is missing or invalid, or if the settings cannot be read for some other reason, returns null. Don't drop the table after migrating your settings, other modules might still need it! Instead, try this method only after you failed to get your settings from Setting.

Parameters

$module_id : int: The module ID

Return values

array<string|int, mixed> —

The settings array on success, null otherwise

add()

Add a new record to the settings


    public
            static        add(string $name, string $value[, int $ord = false ][, string $type = 'text' ][, string $values = '' ][, string $group = null ][, bool $flush = true ]) : bool

The class MUST have been initialized by calling init() or getArray() before this method is called. The present $group stored in the class is used as a default. If the current class $group is empty, it MUST be specified in the call.

Parameters

$name : string: The setting name
$value : string: The value
$ord : int = false: The ordinal value for sorting, defaults to 0
$type : string = 'text': The element type for displaying, defaults to 'text'
$values : string = '': The values for type 'dropdown', defaults to the empty string
$group : string = null: The optional group
$flush : bool = true: Whether to flush the new setting to the repository.

Return values

bool —

True on success, false otherwise

addToArray()

Adds element to array


    public
            static        addToArray(string $name, string $value) : bool

Parameters

$name : string
$value : string

Return values

bool

alter()

Alter an existing setting entry


    public
            static        alter(string $name, string $type[, string $values = '' ][, string $group = '' ][, int $ord = 0 ]) : bool

The class MUST have been initialized by calling init() before this method is called.

Parameters

$name : string: The name of an existing setting entry
$type : string: One of the \Cx\Core\Setting\Controller\Setting::TYPE_* constants
$values : string = '': The type specific values
$group : string = '': The group to use. If not set or set to an empty string, the existing group will be left untouched.
$ord : int = 0: The ordinal value for sorting. If not set or set to 0, the existing ordinal value will be left untouched.

Return values

bool —

True on success, false otherwise

changed()

Returns the current value of the changed flag.


    public
            static        changed() : bool

If it returns true, you probably want to call updateAll().

Return values

bool —

True if values have been changed in memory, false otherwise

delete()

Delete one or more records from the database table


    public
            static        delete([string $name = null ][, string $group = null ]) : bool

For maintenance/update purposes only. At least one of the parameter values must be non-empty. It will fail if both are empty. Mind that in this case, no records will be deleted. Does flush() the currently loaded settings on success.

Parameters

$name : string = null: The optional setting name. Defaults to null
$group : string = null: The optional group. Defaults to null

Return values

bool —

True on success, false otherwise

deleteModule()

Deletes all entries for the current section


    public
            static        deleteModule() : bool

This is for testing purposes only. Use with care! The static $section determines the module affected.

Return values

bool —

True on success, false otherwise

errorHandler()

Should be called whenever there's a problem with the settings table


    public
            static        errorHandler() : bool

Tries to fix or recreate the settings table.

Return values

bool —

False, always.

flush()

Flush the stored settings


    public
            static        flush() : void

Resets the class to its initial state. Does NOT clear the section, however.

getArray()

Returns the settings array for the given section and group


    public
            static        getArray([string $section = null ][, string $group = null ]) : array<string|int, mixed>

See init() on how the arguments are used. If the method is called successively using the same $group argument, the current settings are returned without calling init(). Thus, changes made by calling set() will be preserved.

Parameters

$section : string = null: The section
$group : string = null: The optional group

Return values

array<string|int, mixed> —

The settings array on success, false otherwise

getCurrentEngine()

Returns current Engine name


    public
            static        getCurrentEngine() : type

Return values

type

getCurrentGroup()

Returns current group name


    public
            static        getCurrentGroup() : type

Return values

type

getCurrentSection()

Returns current Section name


    public
            static        getCurrentSection() : string

Return values

string

getCurrentSettings()

Gets current settings based on currently set section, engine and group


    public
            static        getCurrentSettings() : array<string|int, mixed>|false

Return values

array<string|int, mixed>|false

getCurrentTablistName()

Returns the name of the current tab list


    public
            static        getCurrentTablistName() : string

Return values

string —

Name of the current tab list

getCurrentTabName()

Returns the name of the current tab


    public
            static        getCurrentTabName() : string

Return values

string —

Name of the current tab

getEngineType()

Retuns class of the engine


    public
            static        getEngineType() : type

Return values

type

getGroup()


    public
            static        getGroup() : mixed

getInstanceId()

Returns Id of current instance


    public
            static        getInstanceId() : mixed

getSectionEngine()

Returns engine from section


    public
            static        getSectionEngine([type $section = null ][, type $engine = null ]) : type

Parameters

$section : type = null
$engine : type = null

Return values

type

getSettings()

Enhanced method of getting settins by section, engine and group; Recommended for use in future; getArray() is just for backward compatibility


    public
            static        getSettings([type $section = null ][, type $engine = null ][, type $group = null ]) : bool

Parameters

$section : type = null
$engine : type = null
$group : type = null

Return values

bool

getValue()

Returns the settings value stored in the section for the name given.


    public
            static        getValue(string $name[, string $section = null ]) : mixed

If section name is null, the value is retrieved from the default section; If section name is not null, but not initialized, initialize it first.

If the settings have not been initialized (see init()), or if no setting of that name is present in the current set, null is returned.

Parameters

$name : string: The settings name
$section : string = null: The component to fetch the setting from. Leaving this to null is deprecated.

Return values

mixed —

The settings value, if present, null otherwise

init()

Initialize the settings entries from the database with key/value pairs for the current section and the given group


    public
            static        init(string $section[, string $group = null ][, string $engine = 'Database' ][, string $fileSystemConfigRepository = null ][, int $populate = 0 ][, bool $setAsCurrentEngineType = true ]) : bool

An empty $group value is ignored. All records with the section are included in this case. Note that all setting names SHOULD be unambiguous for the entire section. If there are two settings with the same name but different $group values, the second one may overwrite the first!

Parameters

$section : string

The section

$group : string = null

The optional group. Defaults to null

$engine : string = 'Database'

The Engine type Database or File system Default to set Database

$fileSystemConfigRepository : string = null

An optional path to the storage location of config files (/config) which shall be used for the engine 'File System'. Default to set Database

$populate : int = 0

Defines behavior of what to do when section already exists (defaults to NOT_POPULATE):

NOT_POPULATE(0): do nothing
POPULATE(1): add elements to existing array
REPOPULATE(2): replace existing elements

$setAsCurrentEngineType : bool = true

By default this method will set static::$engine, static::$section & static::$group to the arguments $engine, $section & $group. This influences the data returned by static::getValue() when called without argument $section. To prevent the breakage of deprecated code (calls to static::getValue() without argument $section) $setAsCurrentEngineType can be set to false to prevent the override of static::$engine, static::$section & static::$group.

Return values

bool —

True on success, false otherwise

isDefined()

Returns the true or false, if settings name is exist or not .


    public
            static        isDefined(string $name) : bool

If the settings have not been initialized (see init()), or if no setting of that name is present in the current set, false is returned.

Parameters

$name : string: The settings name

Return values

bool —

The settings name, if present, true otherwise false

joinValues()

Joins the strings in the array with commas into a single values string


    public
            static        joinValues(array<string|int, mixed> $arrValues) : string

Commas within the strings are escaped by a backslash (). The array keys are prepended to the values, separated by a colon. Colons within the strings are escaped by a backslash (). Note that keys MUST NOT contain either commas or colons!

Parameters

$arrValues : array<string|int, mixed>: The array of strings

Return values

string —

The concatenated values string

set()

Updates a setting


    public
            static        set(string $name, string $value) : bool

If the setting name exists and the new value is not equal to the old one, it is updated, and $changed set to true. Otherwise, nothing happens, and false is returned

Parameters

$name : string: The settings name
$value : string: The settings value

Return values

bool —

True if the value has been changed, false otherwise, null on noop

setEngineType()

Set engineType


    public
            static        setEngineType(mixed $section, string $engine[, mixed $group = null ]) : mixed

Parameters

$section : mixed
$engine : string
$group : mixed = null

setGroup()


    public
            static        setGroup() : mixed

setSectionEngine()

Sets engine of section.


    public
            static        setSectionEngine(object $oSectionEngine, type $populate) : mixed

If engine of section already exists - acts depending of $populate behavior: NOT_POPULATE(0) - return; POPULATE(1) - add elements to existing array REPOPULATE(2) - replaces section with one given

Parameters

$oSectionEngine : object
$populate : type

show()

Display the settings present in the $arrSettings class array


    public
            static        show(Sigma &$objTemplateLocal, string $uriBase[, string $section = '' ][, string $tab_name = '' ][, string $prefix = 'TXT_' ][, bool $readOnly = false ]) : bool

Uses the indices as the names for any parameter, the values as themselves, and adds language variables for the settings' name with the given prefix (i.e. 'TXT_', or 'TXT_MYMODULE_') plus the upper case indices. Example: Settings: array('shop_dummy' => 1) Prefix: 'TXT_' Results in placeholders to be set as follows: Placeholder Value SETTING_NAME The content of $_ARRAYLANG['TXT_SHOP_DUMMY'] SETTING_VALUE The HTML element for the setting type with a name attribute of 'shop_dummy'

Placeholders: The settings' name is to SETTING_NAME, and the input element to SETTING_VALUE. Set the default block to parse after each array entry if it differs from the default 'core_setting'. Make sure to define all the language variables that are expected to be defined here! In addition, some entries from $_CORELANG are set up. These are both used as placeholder name and language array index:

TXT_CORE_SETTING_STORE
TXT_CORE_SETTING_NAME
TXT_CORE_SETTING_VALUE

The template object is given by reference, and if the block 'core_setting_row' is not present, is replaced by the default backend template. $uriBase SHOULD be the URI for the current module page. If you want your settings to be stored, you MUST handle the post request, check for the 'bsubmit' index in the $_POST array, and call Setting::store().

Parameters

$objTemplateLocal : Sigma: Template object
$uriBase : string: The base URI for the module.
$section : string = '': The optional section header text to add
$tab_name : string = '': The optional tab name to add
$prefix : string = 'TXT_': The optional prefix for language variables. Defaults to 'TXT_'
$readOnly : bool = false: Optional argument to make the generated form read-only. Defaults to false.

Return values

bool —

True on success, false otherwise

show_external()

Adds an external settings view to the current template


    public
            static        show_external(Sigma &$objTemplateLocal, string $tab_name, string $content) : bool

The content must contain the full view, including the surrounding form tags and submit button. Note that these are always appended on the right end of the tab list.

Parameters

$objTemplateLocal : Sigma: Template object
$tab_name : string: The tab name to add
$content : string: The external content

Return values

bool —

True on success

show_section()

Display a section of settings present in the $arrSettings class array


    public
            static        show_section(Sigma &$objTemplateLocal[, string $section = '' ][, string $prefix = 'TXT_' ][, mixed $readOnly = false ]) : bool

See the description of show() for details.

Parameters

$objTemplateLocal : Sigma: The Template object, by reference
$section : string = '': The optional section header text to add
$prefix : string = 'TXT_': The optional prefix for language variables. Defaults to 'TXT_'
$readOnly : mixed = false

Return values

bool —

True on success, false otherwise

splitValues()

Splits the string value at commas and returns an array of strings


    public
            static        splitValues(string $strValues) : array<string|int, mixed>

Commas escaped by a backslash () are ignored and replaced by a single comma. The values themselves may be composed of pairs of key and value, separated by a colon. Colons escaped by a backslash () are ignored and replaced by a single colon. Leading and trailing whitespace is removed from both keys and values. Note that keys MUST NOT contain commas or colons!

Parameters

$strValues : string: The string to be split

Return values

array<string|int, mixed> —

The array of strings

storeFromPost()

Update and store all settings found in the $_POST array


    public
            static        storeFromPost() : bool

Note that you MUST call init() beforehand, or your settings will be unknown and thus not be stored. Sets up an error message on failure.

Return values

bool —

True on success, null on noop, or false on failure

tab_index()

Optionally sets and returns the value of the tab index


    public
            static        tab_index([int $tab_index = null ]) : int

Parameters

$tab_index : int = null: The optional new tab index

Return values

int —

The current tab index

update()

Updates the value for the given name in the settings table


    public
            static        update(string $name) : bool

The class MUST have been initialized before calling this method using init(), and the new value been set(). Sets $changed to true and returns true if the value has been updated successfully. Note that this method does not work for adding new settings. See add() on how to do this. Also note that the loaded setting is not updated, only the database!

Parameters

$name : string: The settings name

Return values

bool —

True on successful update or if unchanged, false on failure

updateAll()

Stores all settings entries present in the $arrSettings object array variable


    public
            static        updateAll() : bool

Returns boolean true if all records were stored successfully, null if nothing changed (noop), false otherwise. Upon success, also resets the $changed class variable to false. The class MUST have been initialized before calling this method using init(), and the new values been set(). Note that this method does not work for adding new settings. See add() on how to do this.

Return values

bool —

True on success, null on noop, false otherwise

verify_template()

Ensures that a valid template is available


    public
            static        verify_template(Sigma &$objTemplateLocal) : mixed

Die()s if the template given is invalid, and Form.html cannot be loaded to replace it.

Parameters

$objTemplateLocal : Sigma: The template, by reference

getValuesFromSelectionAsArray()

Get selectable options as array from string definition


    protected
            static        getValuesFromSelectionAsArray(string $selection) : array<string|int, mixed>

Parameters

$selection : string: Definition of selectable options. Either as comma-separated list or in the for of '{src:/path/to/static/method}'

Return values

array<string|int, mixed> —

List of selectable options

isValidInputFromSelection()

Verify that $input is a valid selection of $selection


    protected
            static        isValidInputFromSelection(mixed $input, string $selection) : bool

Parameters

$input : mixed: Either a string or an array of selected options
$selection : string: Definition of selections

Return values

bool —

TRUE if $input is valid. Otherwise FALSE.

parseFileSizeValue()

Parses value into literal file size notation


    protected
            static        parseFileSizeValue(string $value) : string

Parameters

$value : string: File size in bytes or literal file size notation.

Return values

string —

Literal file size notation. I.e.: 10 MB / 1 GB

Setting in package cloudrexx core setting

Tags

Table of Contents

Constants

Properties

Methods

Constants

NOT_POPULATE

POPULATE

REPOPULATE

TYPE_BUTTON

TYPE_CHECKBOX

TYPE_CHECKBOXGROUP

TYPE_DATE

TYPE_DATETIME

TYPE_DROPDOWN

TYPE_DROPDOWN_MULTISELECT

TYPE_DROPDOWN_USER_CUSTOM_ATTRIBUTE

TYPE_DROPDOWN_USERGROUP

TYPE_EMAIL

TYPE_FILECONTENT

TYPE_FILEUPLOAD

TYPE_IMAGE

TYPE_PASSWORD

TYPE_RADIO

TYPE_TEXT

TYPE_TEXTAREA

TYPE_WYSIWYG

Properties

$arrSettings

$currentTablist

$engine

$engines

$group

$instanceId

$section

$tab_index

$tablists

Methods

__getOldSettings()

Parameters

Tags

Return values

add()

Parameters

Return values

addToArray()

Parameters

Return values

alter()

Parameters

Return values

changed()

Return values

delete()

Parameters

Return values

deleteModule()

Return values

errorHandler()

Tags

Return values

flush()

getArray()

Parameters

Return values

getCurrentEngine()

Return values

getCurrentGroup()

Return values

getCurrentSection()

Return values

getCurrentSettings()

Return values

getCurrentTablistName()

Tags

Return values

getCurrentTabName()

Tags

Return values

Setting
in package

cloudrexx

core

setting