eZ components - Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. contents:: Table of Contents Introduction ============ The Configuration component allows you to read settings. Those settings can come from any backend in theory, but currently there are only two backends implemented: ezcConfigurationIniReader for reading plain configuration files and ezcConfigurationArrayReader for reading parsed configuration files in the form of a PHP array. The latter is faster then the first one. The format for the plain configuration files can be found in the section `File Format`_. Class overview ============== ezcConfigurationManager The main class of this component. It is responsible for calling the configured backends to read in configuration data and return the settings to the application. It implements the singleton pattern and this class can be used in most situations where no special handling of configuration data is required. ezcConfigurationIniReader and ezcConfigurationArrayReader Both classes inherited from the ezcConfigurationFileReader and provide lower level access to reading configuration files. They also provide a method for validating configuration files. ezcConfigurationIniWriter and ezcConfigurationArrayWriter Write configuration files in the format that ezcConfigurationIniReader and ezcConfigurationArrayReader support. ezcConfiguration Is the basic class to query and modify configuration settings. Objects of this class are returned by ezcConfigurationFileReader::getConfig() and can be stored into files through the ezcConfigurationFileWriter::setConfig() method. Basic Usage =========== There are two basic ways to use this component. The first one is through the manager class ezcConfigurationManager. This is mostly suitable for the bulk of your application for retrieving configuration settings. The second way is through the individual reader and writer classes themselves. They provide you with more finegrained control over the settings. Using the Manager ----------------- In this first example you see how configuration settings stored in the file "settings.ini" are accessed: .. include:: tutorial_example_01.php :literal: 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: .. include:: tutorial_example_02.php :literal: 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). Writing Configuration Files =========================== After modifying an ezcConfiguration object with the designated methods there are multiple classes to write the configuration object back to disk. In the next example we write a ezcConfiguration object stored in the variable $cfg to disk: .. include:: tutorial_example_03.php :literal: In line 4 we instantiate the writer object, in the example we use the ezcConfigurationArrayWriter that writes the configuration data as a PHP structure. The component also provides a ezcConfigurationIniWriter class that writes a file that the ezcConfigurationIniReader can read. After initializing the object in line 5 we use the save() method in line 6 to write the configuration file. File Format =========== 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: a) *\\"* which will be replaced with the quote character ("):: "This contains \"quote\" characters" b) *\\\\* 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: .. include:: examples/settings.php :literal: The # element in line 25 contains the comment for the group 'db' (line 23). .. _var_export: http://www.php.net/var_export .. Local Variables: mode: rst fill-column: 79 End: vim: et syn=rst tw=79