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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.config.adapters.xml">
    <title>Zend_Config_Xml</title>

    <para>
        <classname>Zend_Config_Xml</classname> enables developers to store configuration data in a
        simple <acronym>XML</acronym> format and read them via nested object property syntax. The
        root element of the <acronym>XML</acronym> file or string is irrelevant and may be named
        arbitrarily. The first level of <acronym>XML</acronym> elements correspond with
        configuration data sections. The <acronym>XML</acronym> format supports hierarchical
        organization through nesting of <acronym>XML</acronym> elements below the section-level
        elements. The content of a leaf-level <acronym>XML</acronym> element corresponds to the
        value of a configuration datum. Section inheritance is supported by a special
        <acronym>XML</acronym> attribute named <emphasis>extends</emphasis>, and the value of this
        attribute corresponds with the section from which data are to be inherited by the extending
        section.
    </para>

    <note>
        <title>Return Type</title>

        <para>
            Configuration data read into <classname>Zend_Config_Xml</classname> are always returned
            as strings. Conversion of data from strings to other types is left to developers to
            suit their particular needs.
        </para>
    </note>

    <example id="zend.config.adapters.xml.example.using">
        <title>Using Zend_Config_Xml</title>

        <para>
            This example illustrates a basic use of <classname>Zend_Config_Xml</classname> for
            loading configuration data from an <acronym>XML</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.xml</filename>:
        </para>

        <programlisting language="xml"><![CDATA[
<?xml version="1.0"?>
<configdata>
    <production>
        <webhost>www.example.com</webhost>
        <database>
            <adapter>pdo_mysql</adapter>
            <params>
                <host>db.example.com</host>
                <username>dbuser</username>
                <password>secret</password>
                <dbname>dbname</dbname>
            </params>
        </database>
    </production>
    <staging extends="production">
        <database>
            <params>
                <host>dev.example.com</host>
                <username>devuser</username>
                <password>devsecret</password>
            </params>
        </database>
    </staging>
</configdata>
]]></programlisting>

        <para>
            Next, assume that the application developer needs the staging configuration data from
            the <acronym>XML</acronym> file. It is a simple matter to load these data by specifying
            the <acronym>XML</acronym> file and the staging section:
        </para>

        <programlisting language="php"><![CDATA[
$config = new Zend_Config_Xml('/path/to/config.xml', 'staging');

echo $config->database->params->host;   // prints "dev.example.com"
echo $config->database->params->dbname; // prints "dbname"
]]></programlisting>
    </example>

    <example id="zend.config.adapters.xml.example.attributes">
        <title>Using Tag Attributes in Zend_Config_Xml</title>

        <para>
            <classname>Zend_Config_Xml</classname> also supports two additional ways of defining
            nodes in the configuration. Both make use of attributes. Since the
            <emphasis>extends</emphasis> and the <emphasis>value</emphasis> attributes are reserved
            keywords (the latter one by the second way of using attributes), they may not be
            used. The first way of making usage of attributes is to add attributes in a parent
            node, which then will be translated into children of that node:
        </para>

        <programlisting language="xml"><![CDATA[
<?xml version="1.0"?>
<configdata>
    <production webhost="www.example.com">
        <database adapter="pdo_mysql">
            <params host="db.example.com" username="dbuser" password="secret"
                    dbname="dbname"/>
        </database>
    </production>
    <staging extends="production">
        <database>
            <params host="dev.example.com" username="devuser"
                    password="devsecret"/>
        </database>
    </staging>
</configdata>
]]></programlisting>

        <para>
            The other way does not really shorten the config, but keeps it easier to maintain since
            you don't have to write the tag name twice. You simply create an empty tag with the
            value in the <emphasis>value</emphasis> attribute:
        </para>

        <programlisting language="xml"><![CDATA[
<?xml version="1.0"?>
<configdata>
    <production>
        <webhost>www.example.com</webhost>
        <database>
            <adapter value="pdo_mysql"/>
            <params>
                <host value="db.example.com"/>
                <username value="dbuser"/>
                <password value="secret"/>
                <dbname value="dbname"/>
            </params>
        </database>
    </production>
    <staging extends="production">
        <database>
            <params>
                <host value="dev.example.com"/>
                <username value="devuser"/>
                <password value="devsecret"/>
            </params>
        </database>
    </staging>
</configdata>
]]></programlisting>
    </example>

    <note>
        <title>XML strings</title>

        <para>
            <classname>Zend_Config_Xml</classname> is able to load an <acronym>XML</acronym> string
            directly, such as that retrieved from a database. The string is passed
            as the first parameter to the constructor and must start with the
            characters <emphasis>'&lt;?xml'</emphasis>:
        </para>

        <programlisting language="xml"><![CDATA[
$string = <<<EOT
<?xml version="1.0"?>
<config>
    <production>
        <db>
            <adapter value="pdo_mysql"/>
            <params>
                <host value="db.example.com"/>
            </params>
        </db>
    </production>
    <staging extends="production">
        <db>
            <params>
                <host value="dev.example.com"/>
            </params>
        </db>
    </staging>
</config>
EOT;

$config = new Zend_Config_Xml($string, 'staging');
]]></programlisting>
    </note>

    <note>
        <title>Zend_Config XML namespace</title>

        <para>
            <classname>Zend_Config</classname> comes with it's own <acronym>XML</acronym>
            namespace, which adds additional functionality to the parsing process. To take advantage
            of it, you have to define a namespace with the namespace <acronym>URI</acronym>
            <filename>http://framework.zend.com/xml/zend-config-xml/1.0/</filename> in
            your config root node.
        </para>

        <para>
            With the namespace enabled, you can now use <acronym>PHP</acronym> constants within
            your configuration files. Additionally, the <emphasis>extends</emphasis>
            attribute was moved to the new namespace and is deprecated in the
            <constant>NULL</constant> namespace. It will be completely removed there in
            Zend Framework 2.0.
        </para>

        <programlisting language="xml"><![CDATA[
$string = <<<EOT
<?xml version="1.0"?>
<config xmlns:zf="http://framework.zend.com/xml/zend-config-xml/1.0/">
    <production>
        <includePath>
            <zf:const zf:name="APPLICATION_PATH"/>/library</includePath>
        <db>
            <adapter value="pdo_mysql"/>
            <params>
                <host value="db.example.com"/>
            </params>
        </db>
    </production>
    <staging zf:extends="production">
        <db>
            <params>
                <host value="dev.example.com"/>
            </params>
        </db>
    </staging>
</config>
EOT;

define('APPLICATION_PATH', dirname(__FILE__));
$config = new Zend_Config_Xml($string, 'staging');

echo $config->includePath; // Prints "/var/www/something/library"
]]></programlisting>
    </note>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->