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

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

    <para>
        <classname>Zend_Config_Writer</classname> vous donne la possibilité d'écrire des
        fichiers de configuration à partir d'objets <classname>Zend_Config</classname>. Il
        fonctionne avec des adaptateurs détachés du système et est donc très simple à utiliser. Par
        défaut <classname>Zend_Config_Writer</classname> embarque trois adaptateurs, qui
        fonctionnent tous sur la base de fichiers. Vous instanciez un rédacteur ("writer") avec des
        options spécifiques, qui peuvent être <emphasis>filename</emphasis> et
        <emphasis>config</emphasis>. Ensuite
        vous pouvez appeler la méthode <methodname>write()</methodname> du rédacteur et le fichier
        de configuration est créé. Vous pouvez aussi fournir <varname>$filename</varname> et
        <varname>$config</varname> directement à la méthode <methodname>write()</methodname>.
        Actuellement les
        rédacteurs suivants sont embarqués avec <classname>Zend_Config_Writer</classname>&#160;:
    </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>
        Le rédacteur <acronym>INI</acronym> possède deux modes de rendu en fonction des sections.
        Par défaut la configuration de premier niveau est toujours écrite dans des noms de section.
        En appelant <command>$writer->setRenderWithoutSections();</command>, toutes les options
        sont écrites dans l'espace de noms global du fichier <acronym>INI</acronym> et aucune
        section n'est appliquée.
    </para>

    <para>
        De plus, <classname>Zend_Config_Writer_Ini</classname> a un
        paramètre optionnel additionnel <emphasis>nestSeparator</emphasis>, définissant le caractère
        séparant les profondeurs d'imbrication. Par défaut il s'agit du point,
        comme <classname>Zend_Config_Ini</classname> l'accepte par défaut.
    </para>

    <para>
        Lors de la modification ou la création d'objet <classname>Zend_Config</classname>, il
        y a quelques informations à garder en mémoire. Pour créer ou modifier une valeur, vous
        appelez simplement le réglage d'un paramètre d'un objet <classname>Zend_Config</classname>
        grâce à l'accesseur de paramètre ("<emphasis>-&gt;</emphasis>"). Pour créer une section à
        la racine ou pour créer une branche, vous avez juste à créer un nouveau tableau
        (<command>$config-&gt;branch = array();</command>). Pour définir quelle section en étend une
        autre, vous devez appeler la méthode <methodname>setExtend()</methodname> sur l'objet
        <classname>Zend_Config</classname> racine.
    </para>

    <example id="zend.config.writer.example.using">
        <title>Utilisation de Zend_Config_Writer</title>

        <para>
            Cet exemple illustre une utilisation basique
            <classname>Zend_Config_Writer_Xml</classname> pour créer un nouveau fichier de
            configuration&#160;:
        </para>

        <programlisting language="php"><![CDATA[
// Créer l'objet de configuration
$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';

// Ecrire le fichier de l'une des manières suivantes :
// 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>
            Ceci créera un fichier de configuration <acronym>XML</acronym> avec les sections
            "production" et "staging", où "staging" étend "production".
        </para>
    </example>

    <example id="zend.config.writer.modifying">
        <title>Modifier une configuration existante</title>

        <para>
            Cet exemple montre comment modifier un fichier de configuration
            existant&#160;:
        </para>

        <programlisting language="php"><![CDATA[
// Charger toutes les sections d'un fichier de configuration existant,
// tout en évitant les sections étendues.
$config = new Zend_Config_Ini('config.ini',
                              null,
                              array('skipExtends'        => true,
                                    'allowModifications' => true));

// Modifier une valeur
$config->production->hostname = 'foobar';

// Ecrire le fichier
$writer = new Zend_Config_Writer_Ini(array('config'   => $config,
                                           'filename' => 'config.ini'));
$writer->write();
]]></programlisting>
    </example>

    <note>
        <title>Chargement d'un fichier de configuration</title>
        <para>
            Lors du chargement d'un fichier de configuration existant afin de le modifier, il
            est très important de charger toutes les sections et d'éviter les sections étendues,
            évitant ainsi toute fusion de valeurs. Ceci est réalisé en fournissant l'option
            <emphasis>skipExtends</emphasis> au constructeur.
        </para>
    </note>

    <para>
        Pour tous les rédacteurs à base de fichiers (<acronym>INI</acronym>, <acronym>XML</acronym>
        et tableau <acronym>PHP</acronym>), en interne la méthode <methodname>render()</methodname>
        est utilisée pour construire la chaîne de configuration. Cette méthode peut être utilisée
        en dehors de la classe si vous souhaitez accéder à une représentation textuelle de vos
        données de configuration.
    </para>
</sect1>