documentation/manual/en/module_specs/Zend_Config_Ini.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.config.adapters.ini">
   4     <title>Zend_Config_Ini</title>
   5
   6     <para>
   7         <classname>Zend_Config_Ini</classname> enables developers to store configuration data in a
   8         familiar <acronym>INI</acronym> format and read them in the application by using nested
   9         object property syntax. The <acronym>INI</acronym> format is specialized to provide both
  10         the ability to have a hierarchy of configuration data keys and inheritance between
  11         configuration data sections. Configuration data hierarchies are supported by separating the
  12         keys with the dot or period character ("<emphasis>.</emphasis>"). A section may extend or
  13         inherit from another section by following the section name with a colon character
  14         ("<emphasis>:</emphasis>) and the name of the section from which data are to be inherited.
  15     </para>
  16
  17     <note>
  18         <title>Parsing the INI File</title>
  19
  20         <para>
  21             <classname>Zend_Config_Ini</classname> utilizes the <ulink
  22                 url="http://php.net/parse_ini_file"><methodname>parse_ini_file()</methodname></ulink>
  23             <acronym>PHP</acronym> function. Please review this documentation to be aware of its
  24             specific behaviors, which propagate to <classname>Zend_Config_Ini</classname>, such as
  25             how the special values of "<constant>TRUE</constant>", "<constant>FALSE</constant>",
  26             "yes", "no", and "<constant>NULL</constant>" are handled.
  27         </para>
  28     </note>
  29
  30     <note>
  31         <title>Key Separator</title>
  32
  33         <para>
  34             By default, the key separator character is the period character
  35             ("<emphasis>.</emphasis>"). This can be changed, however, by changing the
  36             <varname>$options</varname> key <property>nestSeparator</property> when constructing
  37             the <classname>Zend_Config_Ini</classname> object. For example:
  38         </para>
  39
  40         <programlisting language="php"><![CDATA[
  41 $options['nestSeparator'] = ':';
  42 $config = new Zend_Config_Ini('/path/to/config.ini',
  43                               'staging',
  44                               $options);
  45 ]]></programlisting>
  46     </note>
  47
  48     <example id="zend.config.adapters.ini.example.using">
  49         <title>Using Zend_Config_Ini</title>
  50
  51         <para>
  52             This example illustrates a basic use of <classname>Zend_Config_Ini</classname> for
  53             loading configuration data from an <acronym>INI</acronym> file. In this example there
  54             are configuration data for both a production system and for a staging system. Because
  55             the staging system configuration data are very similar to those for production, the
  56             staging section inherits from the production section. In this case, the decision is
  57             arbitrary and could have been written conversely, with the production section
  58             inheriting from the staging section, though this may not be the case for more complex
  59             situations. Suppose, then, that the following configuration data are contained in
  60             <filename>/path/to/config.ini</filename>:
  61         </para>
  62
  63         <programlisting language="ini"><![CDATA[
  64 ; Production site configuration data
  65 [production]
  66 webhost                  = www.example.com
  67 database.adapter         = pdo_mysql
  68 database.params.host     = db.example.com
  69 database.params.username = dbuser
  70 database.params.password = secret
  71 database.params.dbname   = dbname
  72
  73 ; Staging site configuration data inherits from production and
  74 ; overrides values as necessary
  75 [staging : production]
  76 database.params.host     = dev.example.com
  77 database.params.username = devuser
  78 database.params.password = devsecret
  79 ]]></programlisting>
  80
  81         <para>
  82             Next, assume that the application developer needs the staging configuration data from
  83             the <acronym>INI</acronym> file. It is a simple matter to load these data by specifying
  84             the <acronym>INI</acronym> file and the staging section:
  85         </para>
  86
  87         <programlisting language="php"><![CDATA[
  88 $config = new Zend_Config_Ini('/path/to/config.ini', 'staging');
  89
  90 echo $config->database->params->host;   // prints "dev.example.com"
  91 echo $config->database->params->dbname; // prints "dbname"
  92 ]]></programlisting>
  93     </example>
  94
  95     <note>
  96         <table id="zend.config.adapters.ini.table">
  97             <title>Zend_Config_Ini Constructor Parameters</title>
  98
  99             <tgroup cols="2">
 100                 <thead>
 101                     <row>
 102                         <entry>Parameter</entry>
 103                         <entry>Notes</entry>
 104                     </row>
 105                 </thead>
 106
 107                 <tbody>
 108                     <row>
 109                         <entry><varname>$filename</varname></entry>
 110                         <entry>The <acronym>INI</acronym> file to load.</entry>
 111                     </row>
 112
 113                     <row>
 114                         <entry><varname>$section</varname></entry>
 115
 116                         <entry>
 117                             The [section] within the ini file that is to be loaded. Setting
 118                             this parameter to <constant>NULL</constant> will load all sections.
 119                             Alternatively, an array of section names may be supplied to load
 120                             multiple sections.
 121                         </entry>
 122                     </row>
 123
 124                     <row>
 125                         <entry>
 126                             <varname>$options</varname> (default <constant>FALSE</constant>)
 127                         </entry>
 128
 129                         <entry>
 130                             Options array. The following keys are supported:
 131
 132                             <itemizedlist>
 133                                 <listitem>
 134                                     <para>
 135                                         <emphasis><property>allowModifications</property></emphasis>:
 136                                         Set to <constant>TRUE</constant> to allow subsequent
 137                                         modification of loaded configuration data in-memory.
 138                                         Defaults to <constant>NULL</constant>
 139                                     </para>
 140                                 </listitem>
 141
 142                                 <listitem>
 143                                     <para>
 144                                         <emphasis><property>nestSeparator</property></emphasis>: Set
 145                                         to the character to be used as the nest separator. Defaults
 146                                         to "."
 147                                     </para>
 148                                 </listitem>
 149                             </itemizedlist>
 150                         </entry>
 151                     </row>
 152                 </tbody>
 153             </tgroup>
 154         </table>
 155     </note>
 156 </sect1>
 157 <!--
 158 vim:se ts=4 sw=4 et:
 159 -->