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

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

    <para>
        <classname>Zend_Config_Writer</classname> gives you the ability to write config
        files out of <classname>Zend_Config</classname> objects. It works with an
        adapter-less system and thus is very easy to use. By default
        <classname>Zend_Config_Writer</classname> ships with three adapters, which are all
        file-based. You instantiate a writer with specific options, which
        can be <emphasis>filename</emphasis> and <emphasis>config</emphasis>. Then
        you call the <methodname>write()</methodname> method of the writer and the config
        file is created. You can also give <varname>$filename</varname> and
        <varname>$config</varname> directly to the <methodname>write()</methodname> method.
        Currently the following writers are shipped with
        <classname>Zend_Config_Writer</classname>:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <classname>Zend_Config_Writer_Array</classname>
            </para>
        </listitem>
        <listitem>
            <para>
                <classname>Zend_Config_Writer_Ini</classname>
            </para>
        </listitem>
        <listitem>
            <para>
                <classname>Zend_Config_Writer_Xml</classname>
            </para>
        </listitem>
    </itemizedlist>

    <para>
        The <acronym>INI</acronym> writer has two modes for rendering with regard to sections.
        By default the top-level configuration is always written into section names.
        By calling <command>$writer->setRenderWithoutSections();</command> all options are written
        into the global namespace of the <acronym>INI</acronym> file and no sections are applied.
    </para>

    <para>
        As an addition <classname>Zend_Config_Writer_Ini</classname> has an additional
        option parameter <emphasis>nestSeparator</emphasis>, which defines with which
        character the single nodes are separated. The default is a single dot,
        like it is accepted by <classname>Zend_Config_Ini</classname> by default.
    </para>

    <para>
        When modifying or creating a <classname>Zend_Config</classname> object, there are
        some things to know. To create or modify a value, you simply say set
        the parameter of the <classname>Zend_Config</classname> object via the parameter
        accessor (<emphasis>-&gt;</emphasis>). To create a section in the root or to
        create a branch, you just create a new array
        ("<command>$config-&gt;branch = array();</command>"). To define which section
        extends another one, you call the <methodname>setExtend()</methodname> method
        on the root <classname>Zend_Config</classname> object.
    </para>

    <example id="zend.config.writer.example.using">
        <title>Using Zend_Config_Writer</title>
        <para>
            This example illustrates the basic use of
            <classname>Zend_Config_Writer_Xml</classname> to create a new config file:
        </para>
        <programlisting language="php"><![CDATA[
// Create the config object
$config = new Zend_Config(array(), true);
$config->production = array();
$config->staging    = array();

$config->setExtend('staging', 'production');

$config->production->db = array();
$config->production->db->hostname = 'localhost';
$config->production->db->username = 'production';

$config->staging->db = array();
$config->staging->db->username = 'staging';

// Write the config file in one of the following ways:
// a)
$writer = new Zend_Config_Writer_Xml(array('config'   => $config,
                                           'filename' => 'config.xml'));
$writer->write();

// b)
$writer = new Zend_Config_Writer_Xml();
$writer->setConfig($config)
       ->setFilename('config.xml')
       ->write();

// c)
$writer = new Zend_Config_Writer_Xml();
$writer->write('config.xml', $config);
]]></programlisting>
        <para>
            This will create an <acronym>XML</acronym> config file with the sections production
            and staging, where staging extends production.
        </para>
    </example>

    <example id="zend.config.writer.modifying">
        <title>Modifying an Existing Config</title>
        <para>
            This example demonstrates how to edit an existing config file.
        </para>
        <programlisting language="php"><![CDATA[
// Load all sections from an existing config file, while skipping the extends.
$config = new Zend_Config_Ini('config.ini',
                              null,
                              array('skipExtends'        => true,
                                    'allowModifications' => true));

// Modify a value
$config->production->hostname = 'foobar';

// Write the config file
$writer = new Zend_Config_Writer_Ini(array('config'   => $config,
                                           'filename' => 'config.ini'));
$writer->write();
]]></programlisting>
    </example>

    <note>
        <title>Loading a Config File</title>
        <para>
            When loading an existing config file for modifications it is very
            important to load all sections and to skip the extends, so that
            no values are merged. This is done by giving the
            <emphasis>skipExtends</emphasis> as option to the constructor.
        </para>
    </note>

    <para>
        For all the File-Based writers (<acronym>INI</acronym>, <acronym>XML</acronym> and
        <acronym>PHP</acronym> Array) internally the <methodname>render()</methodname> is used to
        build the configuration string. This method can be used from the outside also if you need
        to access the string-representation of the configuration data.
    </para>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->