Using the Manager

In this first example you see how configuration settings stored in the file "settings.ini" are accessed:

1. <?php
2. require_once 'tutorial_autoload.php';
4. $cfg = ezcConfigurationManager::getInstance();
5. $cfg->init( 'ezcConfigurationIniReader', dirname( __FILE__ ) . '/examples' );
7. $pw = $cfg->getSetting( 'settings', 'db', 'password' );
8. echo "The password is <$pw>.\n";
10. $settings = $cfg->getSettings( 'settings', 'db', array( 'user', 'password' ) );
11. echo "Connecting with {$settings['user']}:{$settings['password']}.\n";
13. list( $user, $pass ) = $cfg->getSettingsAsList( 'settings', 'db', array( 'user', 'password' ) );
14. echo "Connecting with {$user}:{$pass}.\n";
15. ?>

In line 4 and 5 we retrieve an instance of the ezcConfigurationManager class and initialize the system with the init() method. The two arguments specify the reader to use (ezcConfigurationIniReader) and where to find the configuration information. The second argument is the location, and its meaning is dependent on the reader class.

In line 7 we retrieve the setting "password" from the settings group "db" in the configuration named "settings". In the case of the ezcConfigurationIniReader and ezcConfigurationArrayReader the name of the configuration corresponds to a specific file on disk.

Lines 10-11 and 13-14 show two different ways on how to receive a list of settings. The first method returns an associative array, while the second method returns an numerical indexed array which you can f.e. use with the list() construct.

Instead of the ezcConfigurationManager::getSetting() method there is also a number of additional methods that return a setting. These alternative methods also check whether the type of the settings is correct. See f.e. the ezcConfigurationManager::fetchArraySetting() description.

The ezcConfigurationManager::hasSetting() method can be used to find out whether a specific setting exists and the ezcConfigurationManager::hasSettings() methods verifies if all the settings in the list that you give to this method exist. It is preferred to use these methods to see if an setting or list of settings exists before accessing them with one of the get*Setting() methods to prevent exceptions from being thrown.

Using the Reader Classes Directly

Instead of using the manager class, you can also simply retrieve the configuration data directly with the reader classes. The following example illustrates this:

1. <?php
2. require_once 'tutorial_autoload.php';
4. $reader = new ezcConfigurationIniReader();
5. $reader->init( dirname( __FILE__ ), 'settings' );
7. $validationResult = $reader->validate();
8. foreach ( $result->getResultList() as $resultItem )
9. {
10. print $resultItem->file . ":" . $resultItem->line . ":" . $resultItem->column. ":";
11. print " " . $resultItem->details . "\n";
12. }
14. $cfg = $reader->load();
15. ?>

In line 4 we instantiate an object of the ezcConfigurationIniReader class which we initialize in line 5. It is also possible to initialize the reader directly through the constructor but in that case you need to specify the full file name to the configuration file. If you do it in the way that this example does it then you can simply change the classname to f.e. ezcConfigurationArrayReader and your code does not need any changes. The lines 7 to 12 how you can use the validate() method to find out if your configuration file has the correct format. The code in line 14 retrieves the settings from the configuration file and returns them as an ezcConfiguration object. With this object you can read settings and modify the settings. (See the API documentation of ezcConfiguration for those methods).

General Information Regarding Configuration Data

The configuration format consists of four elements:

• Groups, they allow you to group similar settings into one group and it also allows you to have multiple settings with the same name but in different groups. This means that you don't have to prefix your settings with the group name.
• Settings, the name of the setting which identifies the setting. A setting contains a value.
• Values, a value can be of the following types: boolean, integers, floats, arrays and strings.
• Comments, comments belongs to either a group or a setting and can be added to describe what the group contains or what a setting controls.

Group and setting identifiers can only contain the characters a to z, A to Z, 0 to 9, underscore (_), dash (-) and dot (.). The case of settings are preserved but accessing them can be done with any case, this means you cannot have two settings with the same identifier only differing in case.

The following are legal names:

ASimpleName
asimplename
a_simple_name
a.simple.name
a-simple_and.longName

and these are illegal:

A simple name
-=A simple name=-

In addition the group names may contain forward slashes (/), for instance:

a/simple/groupname

Ini File Format

This is the format that is written by the ezcConfigurationIniWriter class and read by the ezcConfigurationIniReader class. The parser itself is located in the ezcConfigurationIniParser class.

The parser will remove leading and trailing whitespace from group names, settings and setting values. If you wish to keep whitespace in a string it will have to be quoted.

Comments are written using a # (hash) and must be placed at the start of the line. The whitespace block before the comment text on all the lines will be trimmed away while whitespace after this block is kept. Trailing whitespace is also trimmed. For instance the follow comments:

# A simple comment
#  A simple comment
#       A simple comment

will become:

#A simple comment
# A simple comment
#      A simple comment

Multiple comment lines will be read as one comment with multiple lines, if there are empty lines in between comments they will be read as empty lines in the comment itself:

# A single line comment
Setting = value

# Multiple lines
# for this
# comment
Setting = value

# Multiple lines

# with empty lines
# for this comment
Setting = value

# Multiple lines
#
# with empty lines
# for this comment
# Actually same as above
Setting = value

Comments are always placed in front of the group or setting. A line that only contains whitespace will be ignored.

The files are always encoded in UTF-8 format, this means it can contain Unicode characters if needed or plain ASCII without specific encoding.

Groups are defined by placing an identifier inside square brackets alone on the string. Any setting that is read after this will be placed as part of this group. Settings without groups are not allowed and will cause an error to be issued. The group name will have its leading and trailing whitespace trimmed away:

[Group1]
[Another group]
[ Yet another group ]

Settings are defined by placing an identifier with an equal sign (=) after it, the value follows after the equal sign. The setting and the value must be on one line, it cannot span multiple lines:

Setting1 = Some example string
Setting2 = 42

The values of settings are generally seen as strings with the exception of:

1. Booleans which can be written as true or false, if you need these strings as text they must be quoted:

   SystemEnabled = true
   LogErrors = false
   

2. Numbers are written using English locale and can be in the following format:

• decimal:

  [1-9][0-9]* | [0]
  
  MaxSize = 400
  MinSize = 0
  

• hexadecimal:

  0[xX][0-9a-fA-F]+
  
  BackgroundColor = 0xaabbcc
  TextColor = 0x0102FE
  

• octal:

  0[0-7]+
  
  Permission = 0666
  

• float:

  LNUM          [0-9]+
  DNUM          ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
  EXPONENT_DNUM ( ({LNUM} | {DNUM}) [eE][+-]? {LNUM})
  
  Price = 10.4
  Seed = 10e5
  

3. An explicit string which is enclosed in double quotes ("), all whitespace is kept inside the quotes and characters are read literally with the exception of escaped characters. The escaped characters are:

1. \" which will be replaced with the quote character ("):

   "This contains \"quote\" characters"
   

2. \\ which will be replaced with the backslash character ():

   "This contains a backslash \\"
   

In addition it is possible to define arrays in a second way by using square brackets ([]) after the setting name and before the equal (=) character. This will make the setting an array and the value is parsed as explained above. In addition the square brackets may be enclosed around a string which turns the array into a hash (or associative array) with the text being used as the key.

List[] = First string
List[] = Second string
List[] = 5
Hash[abc] = 4
Hash["def"] = 5

Array File Format

The Array format can be written using the ezcConfigurationArrayWriter class and read with the ezcConfigurationArrayReader class. The format is a simple var_export of the contained settings and for reading the PHP will parse the file. The file contains an array with two elements. One for the groups and settings and one for the comments. For instance the file could look like:

1. <?php
2. return array (
3. 'settings' =>
4. array (
5. 'site' =>
6. array (
7. 'title' => 'Example site',
8. ),
9. 'db' =>
10. array (
11. 'host' => 'localhost',
12. 'user' => 'root',
13. 'password' => 42,
14. 'connection_retries' => 'five',
15. ),
16. ),
17. 'comments' =>
18. array (
19. 'site' =>
20. array (
21. '#' => ' Settings for the site itself',
22. ),
23. 'db' =>
24. array (
25. '#' => ' Database settings used for all connections',
26. 'password' => ' Storing passwords in INI files is not a good idea,
27. is it?',
28. ),
29. ),
30. );
31. ?>

The # element in line 25 contains the comment for the group 'db' (line 23).