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 <acronym>INI</acronym> format and read them in the application by using nested
        object property syntax. The <acronym>INI</acronym> 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>
            <acronym>PHP</acronym> 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 <property>nestSeparator</property> when constructing
            the <classname>Zend_Config_Ini</classname> object. For example:
        </para>

        <programlisting language="php"><![CDATA[
$options['nestSeparator'] = ':';
$config = new Zend_Config_Ini('/path/to/config.ini',
                              'staging',
                              $options);
]]></programlisting>
    </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 <acronym>INI</acronym> 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 <acronym>INI</acronym> file. It is a simple matter to load these data by specifying
            the <acronym>INI</acronym> 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 <acronym>INI</acronym> file to load.</entry>
                    </row>

                    <row>
                        <entry><varname>$section</varname></entry>

                        <entry>
                            The [section] within the <acronym>INI</acronym> file that is to be
                            loaded. Setting this parameter to <constant>NULL</constant> will load
                            all sections. Alternatively, an array of section names may be supplied
                            to load multiple sections.
                        </entry>
                    </row>

                    <row>
                        <entry>
                            <varname>$options</varname> (default <constant>FALSE</constant>)
                        </entry>

                        <entry>
                            Options array. The following keys are supported:

                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <emphasis><property>allowModifications</property></emphasis>:
                                        Set to <constant>TRUE</constant> to allow subsequent
                                        modification of loaded configuration data in-memory.
                                        Defaults to <constant>NULL</constant>
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <emphasis><property>nestSeparator</property></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:
-->