repo_zf1/documentation/manual/en/module_specs/Zend_Config-TheoryOfOperation.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.config.theory_of_operation">
    <title>Theory of Operation</title>
    <para>
        Configuration data are made accessible to the <classname>Zend_Config</classname> constructor
        through an associative array, which may be multi-dimensional, in order to support
        organizing the data from general to specific. Concrete adapter classes
        adapt configuration data from storage to produce the associative array for the
        <classname>Zend_Config</classname> constructor. User scripts may provide such arrays directly
        to the <classname>Zend_Config</classname> constructor, without using an adapter class, since
        it may be appropriate to do so in certain situations.
    </para>
    <para>
        Each configuration data array value becomes a property of the <classname>Zend_Config</classname> object. The key is used
        as the property name. If a value is itself an array, then the resulting object property is created as a new
        <classname>Zend_Config</classname> object, loaded with the array data. This occurs recursively, such that a hierarchy of
        configuration data may be created with any number of levels.
    </para>
    <para>
        <classname>Zend_Config</classname> implements the <code>Countable</code> and <code>Iterator</code>
        interfaces in order to facilitate simple access to configuration data.
        Thus, one may use the <ulink url="http://php.net/count"><code>count()</code></ulink>
        function and PHP constructs such as
        <ulink url="http://php.net/foreach"><code>foreach</code></ulink> with
        <classname>Zend_Config</classname> objects.
    </para>
    <para>
        By default, configuration data made available through <classname>Zend_Config</classname>
        are read-only, and an assignment (e.g.,
        <code>$config->database->host = 'example.com'</code>)
        results in a thrown exception. This default behavior may be overridden through the constructor,
        however, to allow modification of data values. Also, when modifications are allowed, <classname>Zend_Config</classname>
        supports unsetting of values (i.e. <code>unset($config->database->host);</code>). The
        <code>readOnly()</code> method can be used to determine if modifications to a given <classname>Zend_Config</classname>
        object are allowed and the <code>setReadOnly()</code> method can be used to stop any further
        modifications to a <classname>Zend_Config</classname> object that was created allowing modifications.
        <note>
            <para>
                It is important not to confuse such in-memory modifications with saving configuration
                data out to specific storage media. Tools for creating and modifying configuration
                data for various storage media are out of scope with respect to <classname>Zend_Config</classname>.
                Third-party open source solutions are readily available for the purpose of creating and
                modifying configuration data for various storage media.
            </para>
        </note>
    </para>
    <para>
        Adapter classes inherit from the <classname>Zend_Config</classname> class since they utilize its functionality.
    </para>
    <para>
        The <classname>Zend_Config</classname> family of classes enables configuration data to be
        organized into sections. <classname>Zend_Config</classname> adapter objects may be loaded
        with a single specified section, multiple specified sections, or all sections
        (if none are specified).
    </para>
    <para>
        <classname>Zend_Config</classname> adapter classes support a single inheritance model that
        enables configuration data to be inherited from one section of configuration data
        into another. This is provided in order to reduce or eliminate the need for
        duplicating configuration data for different purposes. An inheriting section
        may also override the values that it inherits through its parent section.
        Like PHP class inheritance, a section may inherit from a parent section,
        which may inherit from a grandparent section, and so on, but multiple inheritance
        (i.e., section C inheriting directly from parent sections A and B) is not supported.
    </para>
    <para>
        If you have two <classname>Zend_Config</classname> objects, you can merge them into a single
        object using the <code>merge()</code> function. For example, given <code>$config</code> and
        <code>$localConfig</code>, you can merge data from <code>$localConfig</code> to <code>$config</code> using
        <code>$config->merge($localConfig);</code>. The items in <code>$localConfig</code> will override
        any items with the same name in <code>$config</code>.
        <note>
            <para>
                The <classname>Zend_Config</classname> object that is performing the merge must have been constructed
                to allow modifications, by passing <code>true</code> as the second parameter of the constructor.
                The <code>setReadOnly()</code> method can then be used to prevent any further modifications
                after the merge is complete.
            </para>
        </note>
    </para>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->