Configuration: ezcConfiguration
[ ]
[ ]
[ ]
[ ]
[ ]
Class: ezcConfiguration
|
This class provides persistent platform-independent and format independent application settings. [
source]
A typical usage for retrieving the settings in an application:
1. $conf = new ezcConfiguration();
2. if ( $conf->hasSettings( 'Colors', array( 'Background', 'Foreground' ) ) )
3. {
4. $colorBg = $conf->getSetting( 'Colors', 'Background' );
5. $colorFg = $conf->getIntSetting( 'Colors', 'Foreground' );
6. }
A typical usage for storing the settings of an application:
1. // $conf contains an ezcConfiguration object
2. $conf->setSetting( 'Colors', 'Background', 'blue' );
3. $conf->setSetting( 'Fonts', 'PointSize', 12 );
4.
5. $conf->setSettings( 'DB',
6. array( 'Host', 'User', 'Password' ),
7. array( 'localhost', 'dr', 'eXaMpLe' ) );
The current groups and their settings can be examined with:
1. // $conf contains an ezcConfiguration object
2. $groups = $conf->getGroupNames();
3. foreach ( $groups as $group )
4. {
5. $settings = $conf->getSettingNames( $group );
6. foreach ( $settings as $setting )
7. {
8. $value = $conf->getSetting( $group, $setting );
9. print "$group:$setting=$value\n";
10. }
11. }
Alternatively all settings and their values can be returned in one go:
1. // $conf contains an ezcConfiguration object
2. $settings = $conf->getSettingsInGroup( 'Colors' );
3. foreach ( $settings as $setting => $value )
4. {
5. print "$setting=$value\n";
6. }
Or quering the entire configuration settings with getAllSettings():
1. // $conf contains an ezcConfiguration object
2. $allSettings = $conf->getAllSettings( 'Colors' );
3. foreach ( $allSettings as $group => $settings )
4. {
5. foreach ( $settings as $setting => $value )
6. {
7. print "$group:$setting=$value\n";
8. }
9. }
Fetching specific settings is done using getSetting() or if you want to ensure that it is a specific type use getBoolSetting(), getIntSetting(), getFloatSetting(), getNumberSetting(), getStringSetting() or getArraySetting(). Fetching multiple values is possible with getSettings().
Removing entries is possible with removeSetting(), removeSettings(), removeGroup() and removeAllSettings().
In addition all entries can queried for existance with hasSetting(), hasSettings() and hasGroup().
Reading and writing is done by the various implemenations of ezcConfigurationReader and ezcConfigurationWriter respectively. They provide access to different configuration formats and storage types, for instance INI files and database storage.
If the application does not need to have such finegrained control over the settings the ezcConfigurationManager class might be of interest.
Method Summary
|
public ezcConfiguration |
__construct(
[$settings = array()], [$comments = array()] )
Constructs the configuration object. |
|
public void |
addGroup(
$group, [$comment = null] )
Adds a the group $group with the comment $comment the settings. |
|
public array(array) |
getAllComments(
)
Returns all the groups and their settings comments as an array. |
|
public array(array) |
getAllSettings(
)
Returns all the groups and their settings and values. |
|
public array |
getArraySetting(
$group, $setting )
Returns the value of the setting $setting in group $group. |
|
public bool |
getBoolSetting(
$group, $setting )
Returns the value of the setting $setting in group $group. |
|
public string |
getComment(
$group, $setting, $setting
)
Returns the comment belonging to setting $setting located in group $group. |
|
public array |
getComments(
$group, $settings )
Returns the comments belonging to the specified settings $settings as an array. |
|
public array |
getGroupNames(
)
Returns the names of all the groups as an array. |
|
public mixed |
getNumberSetting(
$group, $setting )
Returns the value of the setting $setting in group $group. |
|
public mixed |
getSetting(
$group, $setting, $setting
)
Returns the value of setting $setting located in group $group. |
|
public array(string) |
getSettingNames(
$group )
Returns the names of all settings in the group $group. |
|
public array |
getSettings(
$group, $settings )
Returns the values of the settings $settings in group $group as an array. |
|
public array(string=>mixed) |
getSettingsInGroup(
$group )
Returns all settings in the group $group. |
|
public string |
getStringSetting(
$group, $setting )
Returns the value of the setting $setting in group $group. |
|
public bool |
hasGroup(
$group )
Returns true if the group $group exists. |
|
public bool |
hasSetting(
$group, $setting )
Returns true if setting $setting exists within the group $group. |
|
public bool |
hasSettings(
$group, $settings )
Returns true if all the specified settings $settings exists within $group. |
|
public bool |
isModified(
)
Returns true if the configuration has been modified since it was initialized with the constructor. |
|
public void |
removeAllSettings(
)
Removes all groups, settings, values and comments. |
|
public void |
removeGroup(
$group )
Removes the group $group from the settings. |
|
public void |
removeSetting(
$group, $setting )
Removes the setting $setting from the group $group. |
|
public void |
removeSettings(
$group, $settings )
Removes the settings $settings from the group $group. |
|
public void |
setSetting(
$group, $setting, $value, [$comment = null] )
Sets the setting $setting in group $group to $value. |
|
public void |
setSettings(
$group, $settings, $values, [$comments = null] )
Sets the settings $setting in group $group to $values. |
Methods
__construct
ezcConfiguration __construct(
[array
$settings = array()], [array
$comments = array()] )
Constructs the configuration object.
Initializes the configuration object with the groups and the comments. The $settings array contains all the setting groups. The $comments array has the same format. See ezcConfiguration::$settings and ezcConfiguration::$comments for an example of the layout.
Parameters
| Name |
Type |
Description |
$settings |
array |
|
$comments |
array |
|
addGroup
void addGroup(
string
$group, [string
$comment = null] )
Adds a the group $group with the comment $comment the settings.
Parameters
| Name |
Type |
Description |
$group |
string |
|
$comment |
string |
|
Throws
| Class | Description |
|---|
ezcConfigurationGroupExistsAlreadyException |
if the group that you are trying to add already exists. |
getAllComments
array(array) getAllComments(
)
Returns all the groups and their settings comments as an array.
The returned array looks like:
1. array( 'group1' => array( '#' => 'groupcomment',
2. 'setting1' => 'comment1',
3. 'setting2' => 'comment2' ),
4. 'group2' => array( 'setting3' => 'comment3' ) );
getAllSettings
array(array) getAllSettings(
)
Returns all the groups and their settings and values.
The returned array looks like:
1. array( 'group1' => array( 'setting1' => 'value1',
2. 'setting2' => 'value2' ),
3. 'group2' => array( 'setting3' => 'value3' ) );
getArraySetting
array getArraySetting(
string
$group, string
$setting )
Returns the value of the setting $setting in group $group.
Uses the getSetting() method to fetch the value, this method can throw exceptions. This method also validates whether the value is actually an array value.
Parameters
| Name |
Type |
Description |
$group |
string |
|
$setting |
string |
|
Throws
| Class | Description |
|---|
ezcConfigurationUnknownGroupException |
if the group does not exist. |
ezcConfigurationUnknownSettingException |
if the setting does not exist. |
ezcConfigurationSettingWrongTypeException |
if the setting value is not an array. |
See also:
setting.
getBoolSetting
bool getBoolSetting(
string
$group, string
$setting )
Returns the value of the setting $setting in group $group.
Uses the getSetting() method to fetch the value, this method can throw exceptions. This method also validates whether the value is actually a boolean value.
Parameters
| Name |
Type |
Description |
$group |
string |
|
$setting |
string |
|
Throws
| Class | Description |
|---|
ezcConfigurationUnknownGroupException |
if the group does not exist. |
ezcConfigurationUnknownSettingException |
if the setting does not exist. |
ezcConfigurationSettingWrongTypeException |
if the setting value is not a boolean. |
See also:
setting.
getComment
string getComment(
string
$group,
$setting, string
$setting
)
Returns the comment belonging to setting $setting located in group $group.
This method returns the comment belonging to the setting that is passed. If there is no comment for this specific setting it returns false.
Parameters
| Name |
Type |
Description |
$group |
string |
|
$setting
|
string |
|
$setting |
|
|
Throws
| Class | Description |
|---|
ezcConfigurationUnknownGroupException |
if the group does not exist. |
ezcConfigurationUnknownSettingException |
if the setting does not exist. |
getComments
array getComments(
string
$group,
$settings )
Returns the comments belonging to the specified settings $settings as an array.
This method returns the comments belonging to the settings that are passed. If there is no comment for each specific setting the returning array element will have a value of false.
Parameters
| Name |
Type |
Description |
$group |
string |
The name of the group the settings will be located in. |
$settings |
array |
|
Throws
| Class | Description |
|---|
ezcConfigurationUnknownGroupException |
if the group does not exist. |
ezcConfigurationUnknownSettingException |
if one or more of the settings do not exist. |
getGroupNames
array getGroupNames(
)
Returns the names of all the groups as an array.
getNumberSetting
mixed getNumberSetting(
string
$group, string
$setting )
Returns the value of the setting $setting in group $group.
Uses the getSetting() method to fetch the value, this method can throw exceptions. This method also validates whether the value is actually an integer or float value.
Parameters
| Name |
Type |
Description |
$group |
string |
|
$setting |
string |
|
Throws
| Class | Description |
|---|
ezcConfigurationUnknownGroupException |
if the group does not exist. |
ezcConfigurationUnknownSettingException |
if the setting does not exist. |
ezcConfigurationSettingWrongTypeException |
if the setting value is not an integer or a float. |
See also:
setting.
getSetting
mixed getSetting(
string
$group,
$setting, string
$setting
)
Returns the value of setting $setting located in group $group.
Parameters
| Name |
Type |
Description |
$group |
string |
|
$setting
|
string |
|
$setting |
|
|
Throws
| Class | Description |
|---|
ezcConfigurationUnknownGroupException |
if the group does not exist. |
ezcConfigurationUnknownSettingException |
if the setting does not exist. |
getSettingNames
array(string) getSettingNames(
string
$group )
Returns the names of all settings in the group $group.
Parameters
| Name |
Type |
Description |
$group |
string |
|
Throws
| Class | Description |
|---|
ezcConfigurationUnknownGroupException |
if the group does not exist. |
getSettings
array getSettings(
string
$group,
$settings )
Returns the values of the settings $settings in group $group as an array.
For each of the setting names passed in the $settings array it will return the setting in the returned array with the name of the setting as key.
Parameters
| Name |
Type |
Description |
$group |
string |
|
$settings |
array |
|
Throws
| Class | Description |
|---|
ezcConfigurationUnknownGroupException |
if the group does not exist. |
ezcConfigurationUnknownSettingException |
if one or more of the settings do not exist. |
getSettingsInGroup
array(string=>mixed) getSettingsInGroup(
string
$group )
Returns all settings in the group $group.
Parameters
| Name |
Type |
Description |
$group |
string |
|
Throws
| Class | Description |
|---|
ezcConfigurationUnknownGroupException |
if the group does not exist. |
getStringSetting
string getStringSetting(
string
$group, string
$setting )
Returns the value of the setting $setting in group $group.
Uses the getSetting() method to fetch the value, this method can throw exceptions. This method also validates whether the value is actually a string value.
Parameters
| Name |
Type |
Description |
$group |
string |
|
$setting |
string |
|
Throws
| Class | Description |
|---|
ezcConfigurationUnknownGroupException |
if the group does not exist. |
ezcConfigurationUnknownSettingException |
if the setting does not exist. |
ezcConfigurationSettingWrongTypeException |
if the setting value is not a string. |
See also:
setting.
hasGroup
bool hasGroup(
string
$group )
Returns true if the group $group exists.
Parameters
| Name |
Type |
Description |
$group |
string |
|
hasSetting
bool hasSetting(
string
$group, string
$setting )
Returns true if setting $setting exists within the group $group.
Parameters
| Name |
Type |
Description |
$group |
string |
|
$setting |
string |
|
hasSettings
bool hasSettings(
string
$group,
$settings )
Returns true if all the specified settings $settings exists within $group.
Parameters
| Name |
Type |
Description |
$group |
string |
|
$settings |
array(string) |
|
isModified
bool isModified(
)
Returns true if the configuration has been modified since it was initialized with the constructor.
removeAllSettings
void removeAllSettings(
)
Removes all groups, settings, values and comments.
removeGroup
void removeGroup(
string
$group )
Removes the group $group from the settings.
Parameters
| Name |
Type |
Description |
$group |
string |
|
Throws
| Class | Description |
|---|
ezcConfigurationUnknownGroupException |
if the group does not exist. |
removeSetting
void removeSetting(
string
$group, string
$setting )
Removes the setting $setting from the group $group.
Parameters
| Name |
Type |
Description |
$group |
string |
|
$setting |
string |
|
Throws
| Class | Description |
|---|
ezcConfigurationUnknownGroupException |
if the group does not exist. |
ezcConfigurationUnknownSettingException |
if the setting does not exist. |
removeSettings
void removeSettings(
string
$group,
$settings )
Removes the settings $settings from the group $group.
Parameters
| Name |
Type |
Description |
$group |
string |
|
$settings |
array(string) |
|
Throws
| Class | Description |
|---|
ezcConfigurationUnknownGroupException |
if the group does not exist. |
ezcConfigurationUnknownSettingException |
if one or more of the settings do not exist. |
setSetting
void setSetting(
string
$group, string
$setting, mixed
$value, [string
$comment = null] )
Sets the setting $setting in group $group to $value.
If the setting does not already exists it will be created.
Parameters
| Name |
Type |
Description |
$group |
string |
|
$setting |
string |
|
$value |
mixed |
The value of the setting, can be any PHP type except a resource or an object. |
$comment |
string |
The comment belonging to the setting |
setSettings
void setSettings(
string
$group, array(string)
$settings, array(mixed)
$values, [array(string)
$comments = null] )
Sets the settings $setting in group $group to $values.
If the settings do not already exists it will be created.
Parameters
| Name |
Type |
Description |
$group |
string |
|
$settings |
array(string) |
|
$values |
array(mixed) |
|
$comments |
array(string) |
The comment belonging to the setting |
Last updated: Wed, 28 Nov 2007
