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

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

    <sect2 id="zend.config.adapters.yaml.intro">
        <title>Aperçu</title>

        <para>
            <ulink url="http://www.yaml.org/">YAML</ulink> est un acronyme récursif signifiant "YAML
            Ain't Markup Language", et peuyt se résumer en "standard de sérialization de données
            human friendly pour tous les langages de programmation." Il est souvent utilisé pour
            la configuration d'applications.
        </para>

        <para>
            <classname>Zend_Config_Yaml</classname> est une petite extensions de
            <classname>Zend_Config</classname>. Il inclut un analyseur capable de reconnaitre la syntaxe
            YAML utilisées pour des besoins de configuration et permet de préciser d'autres analyseurs
            à utiliser pour le support de syuyntaxes complexes (e.g., ext/syck, spyc, sfYaml, etc.).
        </para>
    </sect2>

    <sect2 id="zend.config.adapters.yaml.quick-start">
        <title>QuickStart</title>

        <para>
            Voici une version YAML de la configuration d'une application standard.
        </para>

        <programlisting language="yaml"><![CDATA[
production:
  phpSettings:
    display_startup_errors: false
    display_errors: false
  includePaths:
    library: APPLICATION_PATH/../library
  bootstrap:
    path: APPLICATION_PATH/Bootstrap.php
    class: "Bootstrap"
  appnamespace: "Application"
  resources:
    frontController:
      controllerDirectory: APPLICATION_PATH/controllers
      moduleDirectory: APPLICATION_PATH/modules
      params:
        displayExceptions: false
    modules:
    db:
      adapter: "pdo_sqlite"
      params:
        dbname: APPLICATION_PATH/../data/db/application.db
    layout:
      layoutPath: APPLICATION_PATH/layouts/scripts/

staging: 
  _extends: production

testing: 
  _extends: production
  phpSettings:
    display_startup_errors: true
    display_errors: true

development:
  _extends: production
  phpSettings:
    display_startup_errors: true
    display_errors: true
  resources:
    frontController:
      params:
        displayExceptions: true

]]></programlisting>

        <para>
            Pour l'utiliser, instanciez simplement <classname>Zend_Config_Yaml</classname> en lui
            indiquant le chemin vers ce fichier ainsi que la section à charger. Par défaut,
            les constantes trouvées dans les valeurs seront substituées par leurs valeurs.
        </para>

        <programlisting language="php"><![CDATA[
$config = new Zend_Config_Yaml(
    APPLICATION_PATH . '/configs/application.yaml',
    APPLICATION_ENV
);
]]></programlisting>

        <para>
            Une fois instancié, l'utilisation est classique, comme un objet de configuration.
        </para>

        <programlisting language="php"><![CDATA[
$db = Zend_Db::factory($config->resources->db);
]]></programlisting>
    </sect2>

    <sect2 id="zend.config.adapters.yaml.options">
        <title>Options de configuration</title>

        <para>
            Les options suivantes peuvent être passées comme clés au troisième paramètre
            <varname>$options</varname> du constructeur.
        </para>

        <variablelist>
            <title>Zend_Config_Yaml Options</title>

            <varlistentry>
                <term>allow_modifications</term>

                <listitem>
                    <para>
                        Par défaut, <classname>Zend_Config</classname> est en lecture seule.
                        Passer cette option à <constant>true</constant> autorisera la modification
                        de l'objet.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>skip_extends</term>

                <listitem>
                    <para>
                        Par défaut, à chaque fois qu'une section étend une autre,
                        <classname>Zend_Config</classname> regroupera cette section avec son parent.
                        Utiliser le booléen <constant>true</constant> pour cette option désactivera ce
                        comportement, la configuration de la section sera telle-quelle.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>ignore_constants</term>

                <listitem>
                    <para>
                        Par défaut, <classname>Zend_Config_Yaml</classname> remplacera toutes les
                        constantes trouvées dans le fichier par leurs valeurs respectives. Passez
                        le booléen <constant>true</constant> à cette option pour désactiver cette
                        fonctionnalité.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>yaml_decoder</term>

                <listitem>
                    <para>
                        Par défaut, <classname>Zend_Config_Yaml</classname> utilise une analyseur interne,
                        <methodname>Zend_Config_Yaml::decode()</methodname>, pour analyser et traiter les
                        fichiers YAML. Vous pouvez préciser une fonction de callback à utiliser comme
                        analyseur externe via cette option.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </sect2>

    <sect2 id="zend.config.adapters.yaml.methods">
        <title>Méthodes disponibles</title>

        <variablelist>
            <varlistentry id="zend.config.adapters.yaml.methods.constructor">
                <term>
                    <methodsynopsis>
                        <methodname>__construct</methodname>
                        <methodparam>
                            <funcparams>$yaml, $section = null, $options = false</funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        Constructeur. <varname>$yaml</varname> doit pointer vers un fichier YAML valide.
                        Si <varname>$section</varname> est précisé, seule la section indiquée sera analysée.
                        <varname>$options</varname> est documenté dans <link
                            linkend="zend.config.adapters.yaml.options">la section options</link>.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry id="zend.config.adapters.yaml.methods.decode">
                <term>
                    <methodsynopsis>
                        <methodname>decode</methodname>
                        <methodparam>
                            <funcparams>$yaml</funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        Analyse et tranforme une chaine YAML en un tableau PHP.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry id="zend.config.adapters.yaml.methods.set-ignore-constants">
                <term>
                    <methodsynopsis>
                        <methodname>setIgnoreConstants</methodname>
                        <methodparam>
                            <funcparams>$flag</funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        Cette méthode <emphasis>statique</emphasis> est utilisée pour changer le
                        comportement global de l'analyse des constantes trouvées dans les fichiers
                        YAML. Par défaut, les constantes sont remplacées par leurs valeurs. Passer
                        le booléen <constant>true</constant> à cette méthode surchargera ce
                        comportement. (Vous pouvez changer le comportement par instance en utilisant
                        l'option <varname>ignore_constants</varname>.)
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry id="zend.config.adapters.yaml.methods.ignore-constants">
                <term>
                    <methodsynopsis>
                        <methodname>ignoreConstants</methodname>
                        <methodparam>
                            <funcparams></funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        Cette méthode <emphasis>statique</emphasis> retourne la valeur actuelle
                        de <varname>ignore_constants</varname>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </sect2>

    <sect2 id="zend.config.adapters.yaml.examples">
        <title>Exemples</title>

        <example id="zend.config.adapters.yaml.examples.sf-yaml">
            <title>Utiliser Zend_Config_Yaml avec sfYaml</title>

            <para>
                Comme précisé dans la <link linkend="zend.config.adapters.yaml.options">section des options
                </link>, <classname>Zend_Config_Yaml</classname> vous permet de spécifier votre propre
                analyseur YAML.
            </para>

            <para>
                <ulink url="http://components.symfony-project.org/yaml/">sfYaml</ulink> est un <ulink
                    url="http://components.symfony-project.org/">Symfony component</ulink> qui implémente
                un analyseur YAML complet pour PHP, et inclus des fonctionnalités additionnelles comme l'analyse
                d'expressions PHP incluses dans du YAML. Dans cet exemple, nous utilisons
                <methodname>sfYaml::load()</methodname> comme méthode callback pour le décodage du YAML.
                <emphasis>(Note: ceci suppose que la classe <classname>sfYaml</classname> est déja chargée
                ou disponible pour auto-chargement.)</emphasis>
            </para>

            <programlisting language="php"><![CDATA[
$config = new Zend_Config_Yaml(
    APPLICATION_PATH . '/configs/application.yaml',
    APPLICATION_ENV,
    array('yaml_decoder' => array('sfYaml', 'load'))
);
]]></programlisting>
        </example>
    </sect2>
</sect1>