repo_zf1/documentation/manual/en/module_specs/Zend_Config_Ini.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.config.adapters.ini">
    <title>Zend_Config_Ini</title>
    <para>
        <classname>Zend_Config_Ini</classname> enables developers to store configuration data in a
        familiar INI format and read them in the application by using nested object property syntax.
        The INI format is specialized to provide both the ability to have a hierarchy of
        configuration data keys and inheritance between configuration data sections. Configuration
        data hierarchies are supported by separating the keys with the dot or period character
        ("<emphasis>.</emphasis>"). A section may extend or inherit from another section by
        following the section name with a colon character ("<emphasis>:</emphasis>) and the name of
        the section from which data are to be inherited.
    </para>
    <note>
        <title>Parsing the INI File</title>
        <para>
            <classname>Zend_Config_Ini</classname> utilizes the <ulink
                url="http://php.net/parse_ini_file"><methodname>parse_ini_file()</methodname></ulink>
            PHP function. Please review this documentation to be aware of its specific behaviors,
            which propagate to <classname>Zend_Config_Ini</classname>, such as how the special
            values of "<constant>TRUE</constant>", "<constant>FALSE</constant>", "yes", "no",
            and "<constant>NULL</constant>" are handled.
        </para>
    </note>
    <note>
        <title>Key Separator</title>
        <para>
            By default, the key separator character is the period character
            ("<emphasis>.</emphasis>"). This can be changed, however, by changing the
            <varname>$options</varname> key <emphasis>'nestSeparator'</emphasis> when constructing
            the <classname>Zend_Config_Ini</classname> object. For example:
            <programlisting language="php"><![CDATA[
$options['nestSeparator'] = ':';
$config = new Zend_Config_Ini('/path/to/config.ini',
                              'staging',
                              $options);
]]></programlisting>
        </para>
    </note>
    <example id="zend.config.adapters.ini.example.using">
        <title>Using Zend_Config_Ini</title>
        <para>
            This example illustrates a basic use of <classname>Zend_Config_Ini</classname> for
            loading configuration data from an INI file. In this example there are configuration
            data for both a production system and for a staging system. Because the staging system
            configuration data are very similar to those for production, the staging section
            inherits from the production section. In this case, the decision is arbitrary and could
            have been written conversely, with the production section inheriting from the staging
            section, though this may not be the case for more complex situations. Suppose, then,
            that the following configuration data are contained in
            <filename>/path/to/config.ini</filename>:
        </para>
        <programlisting language="ini"><![CDATA[
; Production site configuration data
[production]
webhost                  = www.example.com
database.adapter         = pdo_mysql
database.params.host     = db.example.com
database.params.username = dbuser
database.params.password = secret
database.params.dbname   = dbname

; Staging site configuration data inherits from production and
; overrides values as necessary
[staging : production]
database.params.host     = dev.example.com
database.params.username = devuser
database.params.password = devsecret
]]></programlisting>
        <para>
            Next, assume that the application developer needs the staging configuration data from
            the INI file. It is a simple matter to load these data by specifying the INI file and
            the staging section:
        </para>
        <programlisting language="php"><![CDATA[
$config = new Zend_Config_Ini('/path/to/config.ini', 'staging');

echo $config->database->params->host;   // prints "dev.example.com"
echo $config->database->params->dbname; // prints "dbname"
]]></programlisting>
    </example>
    <note>
    <table id="zend.config.adapters.ini.table">
        <title>Zend_Config_Ini Constructor Parameters</title>
        <tgroup cols="2">
            <thead>
                  <row>
                    <entry>Parameter</entry>
                    <entry>Notes</entry>
                </row>
            </thead>
            <tbody>
                <row>
                    <entry><varname>$filename</varname></entry>
                    <entry>The INI file to load.</entry>
                </row>
                <row>
                    <entry><varname>$section</varname></entry>
                    <entry>The [section] within the ini file that is to be loaded. Setting
                        this parameter to null will load all sections. Alternatively, an
                        array of section names may be supplied to load multiple sections.</entry>
                </row>
                <row>
                    <entry><varname>$options = false</varname></entry>
                    <entry>Options array. The following keys are supported:
                        <itemizedlist>
                            <listitem>
                                <para>
                                    <emphasis>allowModifications</emphasis>: Set to true to allow
                                    subsequent modification of loaded file. Defaults to false
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>nestSeparator</emphasis>: Set to the character to be
                                    used as the nest separator. Defaults to "."
                                </para>
                            </listitem>
                        </itemizedlist>
                    </entry>
                </row>
            </tbody>
        </tgroup>
    </table>
    </note>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->