repo_zf1/documentation/manual/fr/module_specs/Zend_Log-Factory.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24604 -->
<!-- Reviewed: no -->
<sect1 id="zend.log.factory">
    <title>Utiliser la fabrique pour créer des logs</title>

    <para>
        En plus de pouvoir instancier les objets directement, il est possible d'utiliser une fabrique,
        la méthode <methodname>factory()</methodname> d'une instance Log, et il est possible de configurer
        les objets d'écriture (writers) et leurs filtres. En utilisant la fabrique, vous pouvez attacher
        plusieurs objets d'écriture dont la configuration peut être passée sous forme de tableau ou d'objet
        <classname>Zend_Config</classname>.
    </para>

    <para>
        Un exemple:
    </para>

    <programlisting language="php"><![CDATA[
$logger = Zend_Log::factory(array(
    'timestampFormat' => 'Y-m-d',
    array(
        'writerName'   => 'Stream',
        'writerParams' => array(
            'stream'   => '/tmp/zend.log',
        ),
        'formatterName' => 'Simple',
        'formatterParams' => array(
            'format'   => '%timestamp%: %message% -- %info%',
        ),
        'filterName'   => 'Priority',
        'filterParams' => array(
            'priority' => Zend_Log::WARN,
        ),
    ),
    array(
        'writerName'   => 'Firebug',
        'filterName'   => 'Priority',
        'filterParams' => array(
            'priority' => Zend_Log::INFO,
        ),
    ),
));
]]></programlisting>

    <para>
        Le code ci-dessus instancie un objet journal et 2 objets d'écriture dont un vers un
        fichier local, puis un vers Firebug. Chacun possède un filtre sur la priorité avec
        un niveau maximum différent.
    </para>

    <para>
        Les évènements sont journalisés avec le format de date ISO 8601 par défaut. Vous
        pouvez choisir votre propre format avec l'option <emphasis>timestampFormat</emphasis>.
    </para>

    <para>
        Chaque objet d'écriture support les options suivantes:
    </para>

    <variablelist>
        <varlistentry>
            <term>writerName (requis)</term>

            <listitem>
                <para>
                    Le nom "court" de l'objet d'écriture; le nom sans le préfixe. Voyez
                    "writerNamespace" pour plus de détails, des exemples sont : "Mock",
                    "Stream", "Firebug".
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>writerParams (optionnel)</term>

            <listitem>
                <para>
                    Tableau associatif de paramètre à utiliser à l'instanciation de l'objet d'écriture.
                    Chaque méthode <methodname>factory()</methodname> fera suivre ces paramètres.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>writerNamespace (optionnel)</term>

            <listitem>
                <para>
                    Le préfixe de classe ou espace de nom(namespace) à utiliser pour créer le nom de classe
                    complet de l'objet d'écriture. Par défault : "Zend_Log_Writer".
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>formatterName (optionnel)</term>

            <listitem>
                <para>
                    Le nom "court" d'un formateur à utiliser sur l'objet d'écriture. Voyez
                    "formatterNamespace" pour plus de détails. Exemples: "Simple", "Xml".
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>formatterParams (optionnel)</term>

            <listitem>
                <para>
                    Tableau associatif de paramètre à utiliser à l'instanciation de l'objet formateur.
                    Chaque méthode <methodname>factory()</methodname> fera suivre ces paramètres.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>formatterNamespace (optionnel)</term>

            <listitem>
                <para>
                    Le préfixe de classe ou espace de nom(namespace) à utiliser pour créer le nom de classe
                    complet de l'objet formateur. Par défault : "Zend_Log_Formatter".
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>filterName (optionnel)</term>

            <listitem>
                <para>
                    Le nom "court" d'un filtre à utiliser sur l'objet d'écriture. Voyez "filterNamespace"
                    pour plus de détails. Exemples: "Message", "Priority".
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>filterParams (optionnel)</term>

            <listitem>
                <para>
                    Tableau associatif de paramètre à utiliser à l'instanciation de l'objet filtre.
                    Chaque méthode <methodname>factory()</methodname> fera suivre ces paramètres.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>filterNamespace (optionnel)</term>

            <listitem>
                <para>
                    Le préfixe de classe ou espace de nom(namespace) à utiliser pour créer le nom de classe
                    complet de l'objet filtre. Par défault : "Zend_Log_Filter".
                </para>
            </listitem>
        </varlistentry>
    </variablelist>

    <para>
        Chaque objet d'écriture et chaque filtre possède des options.
    </para>

    <sect2 id="zend.log.factory.writer-options">
        <title>Options pour les objets d'écriture</title>

        <sect3 id="zend.log.factory.writer-options.db">
            <title>Zend_Log_Writer_Db Options</title>

            <variablelist>
                <varlistentry>
                    <term>db</term>

                    <listitem>
                        <para>
                            Une instance de <classname>Zend_Db_Adapter</classname>
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>table</term>

                    <listitem>
                        <para>
                            Nom de la table à utiliser.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>columnMap</term>

                    <listitem>
                        <para>
                            Tableau associatif de correspondance entre les noms des colonnes de la table
                            et les champs des évènements du journal.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

        <sect3 id="zend.log.factory.writer-options.firebug">
            <title>Zend_Log_Writer_Firebug Options</title>

            <para>
                Aucune option n'est acceptée par cet objet d'écriture.
            </para>
        </sect3>

        <sect3 id="zend.log.factory.writer-options.mail">
            <title>Zend_Log_Writer_Mail Options</title>

            <table id="zend.log.factory.writer-options.mail.table">
                <title>Zend_Log_Writer_Mail Options</title>

                <tgroup cols="4">
                    <thead>
                        <row>
                            <entry>Option</entry>
                            <entry>Type de données</entry>
                            <entry>Valeur par défaut</entry>
                            <entry>Description</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry><emphasis>mail</emphasis></entry>
                            <entry><type>String</type></entry>
                            <entry><classname>Zend_Mail</classname></entry>

                            <entry>
                                Une instance de <classname>Zend_Mail</classname>
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>charset</emphasis></entry>
                            <entry><type>String</type></entry>
                            <entry>iso-8859-1</entry>

                            <entry>
                                L'encodage pour le courriel
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>from</emphasis></entry>
                            <entry><type>String</type> or <type>Array</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                Expéditeur du courriel.

                                Les paramètres pour un type <type>Array</type> sont :
                                <itemizedlist>
                                    <listitem>
                                        <para>
                                            <property>email</property> : adresse de l'expéditeur
                                        </para>
                                    </listitem>

                                    <listitem>
                                        <para>
                                            <property>name</property> : nom de l'expéditeur
                                        </para>
                                    </listitem>
                                </itemizedlist>
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>to</emphasis></entry>
                            <entry><type>String</type> or <type>Array</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                Destinataire(s) du courriel
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>cc</emphasis></entry>
                            <entry><type>String</type> or <type>Array</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                Destinataire(s) en copie(s) du courriel
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>bcc</emphasis></entry>
                            <entry><type>String</type> or <type>Array</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                Destinataire(s) en copie(s) cachée(s) du courriel
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>subject</emphasis></entry>
                            <entry><type>String</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                Sujet du courriel
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>subjectPrependText</emphasis></entry>
                            <entry><type>String</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                Un résumé du nombre de chaque niveau d'erreurs sera ajouté
                                à la suite du sujet du courriel
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>layout</emphasis></entry>
                            <entry><type>String</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                Une instance de <classname>Zend_Layout</classname>
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>layoutOptions</emphasis></entry>
                            <entry><type>Array</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                Voir la section <xref linkend="zend.layout.options" />
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>layoutFormatter</emphasis></entry>
                            <entry><type>String</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                Une instance de <classname>Zend_Log_Formatter_Interface</classname>
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </sect3>

        <sect3 id="zend.log.factory.writer-options.mock">
            <title>Zend_Log_Writer_Mock Options</title>

            <para>
                Aucune option n'est acceptée par cet objet d'écriture.
            </para>
        </sect3>

        <sect3 id="zend.log.factory.writer-options.null">
            <title>Zend_Log_Writer_Null Options</title>

            <para>
                Aucune option n'est acceptée par cet objet d'écriture.
            </para>
        </sect3>

        <sect3 id="zend.log.factory.writer-options.stream">
            <title>Zend_Log_Writer_Stream Options</title>

            <variablelist>
                <varlistentry>
                    <term>stream|url</term>

                    <listitem>
                        <para>
                            Un identifiant de flux <acronym>PHP</acronym> valide vers lequel journaliser.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>mode</term>

                    <listitem>
                        <para>
                            Le mode I/O (Lecture/Ecriture) à utiliser; défaut : "a" pour "append".
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

        <sect3 id="zend.log.factory.writer-options.syslog">
            <title>Zend_Log_Writer_Syslog Options</title>

            <variablelist>
                <varlistentry>
                    <term>application</term>

                    <listitem>
                        <para>
                            Nom de l'application utilisé par le journaliseur syslog.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>facility</term>

                    <listitem>
                        <para>
                            Facility utilisée par le journal syslog.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

        <sect3 id="zend.log.factory.writer-options.zendmonitor">
            <title>Zend_Log_Writer_ZendMonitor Options</title>

            <para>
               Aucune option n'est acceptée par cet objet d'écriture.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.log.factory.filter-options">
        <title>Options des filtres</title>

        <sect3 id="zend.log.factory.filter-options.message">
            <title>Zend_Log_Filter_Message Options</title>

            <variablelist>
                <varlistentry>
                    <term>regexp</term>

                    <listitem>
                        <para>
                            Expression régulière à faire correspondre par rapport au message du journal.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

        <sect3 id="zend.log.factory.filter-options.priority">
            <title>Zend_Log_Filter_Priority Options</title>

            <variablelist>
                <varlistentry>
                    <term>priority</term>

                    <listitem>
                        <para>
                            La priorité maximale à journaliser.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>operator</term>

                    <listitem>
                        <para>
                            L'opérateur de comparaison (supérieur ou inférieur) à utiliser pour la comparaison,
                            "&lt;=" est utilisé par défaut.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

        <sect3 id="zend.log.factory.filter-options.suppress">
            <title>Zend_Log_Filter_Suppress Options</title>

            <para>
                Aucune option n'est acceptée par cet objet d'écriture.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.log.factory.custom">
        <title>Créer des objets d'écriture et des filtres configurés</title>

        <para>
            SI vous souhaitez créer vos propres objets d'écriture du journal, ou vos propres filtres, il est
            possible de les rendre compatibles avec <methodname>Zend_Log::factory()</methodname> facilement.
        </para>

        <para>
            Vous devez au minimum implémenter
            <interfacename>Zend_Log_FactoryInterface</interfacename>, qui attend une méthode statique
            <methodname>factory()</methodname> accéptant un seul argument,
            <varname>$config</varname>, de types tableau ou instance de
            <classname>Zend_Config</classname>. Si vos objets étendent
            <classname>Zend_Log_Writer_Abstract</classname>, ou vos filtres étendent
            <classname>Zend_Log_Filter_Abstract</classname>, alors ce sera tout.
        </para>

        <para>
            Après, définissez la correspondance entre les options de configuration et les arguments du
            constructeur. Par exemple :
        </para>

        <programlisting language="php"><![CDATA[
class My_Log_Writer_Foo extends Zend_Log_Writer_Abstract
{
    public function __construct($bar, $baz)
    {
        // ...
    }

    public static function factory($config)
    {
        if ($config instanceof Zend_Config) {
            $config = $config->toArray();
        }
        if (!is_array($config)) {
            throw new Exception(
                'factory attend un tableau ou un Zend_Config'
            );
        }

        $default = array(
            'bar' => null,
            'baz' => null,
        );
        $config = array_merge($default, $config);

        return new self(
            $config['bar'],
            $config['baz']
        );
    }
}
]]></programlisting>

        <para>
            Aussi, il est possible d'appeler les setters après l'instanciation, mais avant de retourner
            l'instance:
        </para>

        <programlisting language="php"><![CDATA[
class My_Log_Writer_Foo extends Zend_Log_Writer_Abstract
{
    public function __construct($bar = null, $baz = null)
    {
        // ...
    }

    public function setBar($value)
    {
        // ...
    }

    public function setBaz($value)
    {
        // ...
    }

    public static function factory($config)
    {
        if ($config instanceof Zend_Config) {
            $config = $config->toArray();
        }
        if (!is_array($config)) {
            throw new Exception(
                'factory attend un tableau ou un Zend_Config'
            );
        }

        $writer = new self();
        if (isset($config['bar'])) {
            $writer->setBar($config['bar']);
        }
        if (isset($config['baz'])) {
            $writer->setBaz($config['baz']);
        }
        return $writer;
    }
}
]]></programlisting>
    </sect2>
</sect1>