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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24604 -->
<!-- Reviewed: no -->
<sect1 id="zend.log.overview">
    <title>Présentation</title>

    <para>
        <classname>Zend_Log</classname> est un composant destiné à tous les usages du log. Il
        supporte l'écriture multiple centralisée, formate les messages envoyés vers les logs, et les
        filtre. Ces fonctions sont divisées en objets suivants : <itemizedlist>
                <listitem>
                <para>
                    Un enregistreur (instance de <classname>Zend_Log</classname>) est l'objet
                    que votre application emploie le plus. Vous pouvez avoir autant d'objets
                    d'enregistreur que vous voulez ; ils n'agissent pas l'un sur l'autre. Un objet
                    enregistreur doit contenir au moins un rédacteur (Writer), et peut
                    facultativement contenir un ou plusieurs filtres.
                </para>
            </listitem>

            <listitem>
                <para>
                    Un rédacteur [ou Writer] (hérite de
                    <classname>Zend_Log_Writer_Abstract</classname>) est responsable de la
                    sauvegarde des données dans le stockage.
                </para>
            </listitem>

            <listitem>
                <para>
                    Un filtre (implémente <classname>Zend_Log_Filter_Interface</classname>)
                    bloque des données de log ne devant pas être écrites. Un filtre peut être
                    appliqué à un rédacteur en particulier, ou à tous les rédacteurs. Dans l'un ou
                    l'autre cas, les filtres peuvent être enchaînés.
                </para>
            </listitem>

            <listitem>
                <para>
                    Un formateur (implémente
                    <classname>Zend_Log_Formatter_Interface</classname>) peut formater les données
                    de log avant qu'elles soient écrites par un rédacteur. Chaque rédacteur a
                    exactement un formateur.
                </para>
            </listitem>
            </itemizedlist>
        </para>

    <sect2 id="zend.log.overview.creating-a-logger">
        <title>Créer un log</title>

        <para>
            Pour commencer à enregistrer, instanciez un rédacteur et passez le à une instance
            d'un enregistreur : <programlisting language="php"><![CDATA[
$logger = new Zend_Log();
$redacteur = new Zend_Log_Writer_Stream('php://output');

$logger->addWriter($redacteur);
]]></programlisting> Il est important de noter que l'enregistreur doit avoir au moins un
            rédacteur. Vous pouvez ajouter tout nombre de rédacteurs en utilisant la méthode
            <methodname>addWriter()</methodname>.
        </para>

        <para>
            Alternativement, vous pouvez passer un rédacteur directement au constructeur de
            l'enregistreur : <programlisting language="php"><![CDATA[
$logger = new Zend_Log(new Zend_Log_Writer_Stream('php://output'));
]]></programlisting> L'enregistreur est maintenant prêt à être utilisé.
</para>
    </sect2>

    <sect2 id="zend.log.overview.logging-messages">
        <title>Messages de logs</title>

        <para>
            Pour enregistrer un message, appelez la méthode <methodname>log()</methodname> de l'instance
            de l'enregistreur et passez lui le message avec son niveau de priorité. <programlisting
            role="php"><![CDATA[
$logger->log("Message d'information", Zend_Log::INFO);
]]></programlisting> Le premier paramètre de la méthode <methodname>log()</methodname> est une chaîne
            <code>message</code> et le deuxième paramètre est une <code>priority</code> fourni en
            nombre entier. La priorité doit être l'une des priorités identifiées par l'instance de
            l'enregistreur. Ceci est expliqué dans la prochaine section.
        </para>

        <para>
            Un raccourci est également disponible. Au lieu d'appeler la méthode
            <methodname>log()</methodname>, vous pouvez appeler une méthode par le même nom que la priorité :
            <programlisting language="php"><![CDATA[
$logger->log("Message d'information", Zend_Log::INFO);
$logger->info("Message d'information");

$logger->log("Message d'urgence", Zend_Log::EMERG);
$logger->emerg("Message d'urgence");
]]></programlisting></para>
        </sect2>

        <sect2 id="zend.log.overview.destroying-a-logger">
            <title>Détruire un log</title>

        <para>
            Si l'objet enregistreur n'est plus nécessaire, vous devez affectez la valeur
            <constant>NULL</constant> à la variable le contenant pour le détruire. Ceci appellera
            automatiquement la méthode <methodname>shutdown()</methodname> de chaque rédacteur avant que l'objet
            enregistreur ne soit détruit : <programlisting language="php"><![CDATA[
$logger = null;
]]></programlisting> Explicitement détruire le log de cette façon est facultatif et est exécuté
            automatiquement à la fermeture de PHP.
        </para>
    </sect2>

    <sect2 id="zend.log.overview.builtin-priorities">
        <title>Utiliser les priorités intégrées</title>

        <para>
            La classe de <classname>Zend_Log</classname> définit les priorités suivantes :
            <programlisting language="php"><![CDATA[
EMERG   = 0;  // Urgence : le système est inutilisable
ALERT   = 1;  // Alerte: une mesure corrective
              // doit être prise immédiatement
CRIT    = 2;  // Critique : états critiques
ERR     = 3;  // Erreur: états d'erreur
WARN    = 4;  // Avertissement: états d'avertissement
NOTICE  = 5;  // Notice: normal mais état significatif
INFO    = 6;  // Information: messages d'informations
DEBUG   = 7;  // Debug: messages de déboguages
]]></programlisting> Ces priorités sont toujours disponibles, et une méthode de convenance de
            même nom est disponible pour chacun.
        </para>

        <para>
            Les priorités ne sont pas arbitraires. Elles viennent du protocole BSD
            <code>syslog</code>, qui est décrit dans la <ulink
            url="http://tools.ietf.org/html/rfc3164">RFC-3164</ulink>. Les noms et les niveaux de
            priorité correspondants sont également compatibles avec un autre système de log de <acronym>PHP</acronym>,
            <ulink url="http://pear.php.net/package/log">PEAR Log</ulink>, ce qui favorise
            l'interopérabilité entre lui et <classname>Zend_Log</classname>.
        </para>

        <para>
            Les numéros de priorité descendent par ordre d'importance. <constant>EMERG</constant> (0)
            est la priorité la plus importante. <constant>DEBUG</constant> (7) est la priorité la moins
            importante des priorités intégrées. Vous pouvez définir des priorités d'importance
            inférieure que <constant>DEBUG</constant>. En choisissant la priorité pour votre message de log,
            faîtes attention à cette hiérarchie prioritaire et choisissez convenablement.
        </para>
    </sect2>

    <sect2 id="zend.log.overview.user-defined-priorities">
        <title>Ajouter ses propres priorités</title>

        <para>
            Des priorités définies par l'utilisateur peuvent être ajoutées en cours
            d'exécution en utilisant la méthode de <methodname>addPriority()</methodname> de l'enregistreur :
            <programlisting language="php"><![CDATA[
$logger->addPriority('ESSAI', 8);
]]></programlisting> L'extrait ci-dessus crée une nouvelle priorité, <constant>ESSAI</constant>, dont la
            valeur est <code>8</code>. La nouvelle priorité est alors disponible pour l'enregistreur
            : <programlisting language="php"><![CDATA[
$logger->log("Message d'essai", 8);
$logger->essai("Message d'essai");
]]></programlisting> Les nouvelles priorités ne peuvent pas surcharger celles existantes.
        </para>
    </sect2>

    <sect2 id="zend.log.overview.understanding-fields">
        <title>Comprendre les événements de logs</title>

        <para>
            Quand vous appelez la méthode <methodname>log()</methodname> ou l'un de ses raccourcis, un
            événement de log est créé. C'est simplement un tableau associatif avec des données
            décrivant l'événement qui est envoyé aux rédacteurs. Les clés suivantes sont toujours
            créées dans ce tableau : <code>timestamp</code>, <code>message</code>,
            <code>priority</code>, et <code>priorityName</code>.
        </para>

        <para>
            La création du tableau <code>event</code> est complètement transparente.
            Cependant, la connaissance du tableau d'événement est exigée pour ajouter un élément qui
            n'existerait pas dans le réglage par défaut ci-dessus.
        </para>

        <para>
            Pour ajouter un nouvel élément à chaque futur événement, appeler la méthode
            <methodname>setEventItem()</methodname> en donnant une clé et une valeur : <programlisting
            role="php"><![CDATA[
$logger->setEventItem('pid', getmypid());
]]></programlisting> L'exemple ci-dessus place un nouvel élément nommé <code>pid</code> et lui
            donne comme valeur le PID du processus courant. Une fois qu'un nouvel élément a été
            placé, il est disponible automatiquement pour tous les rédacteurs avec toutes les autres
            données d'événement pendant l'enregistrement. Un élément peut être surchargé à tout
            moment en appelant une nouvelle fois la méthode <methodname>setEventItem()</methodname>.
        </para>

        <para>
            Le réglage d'un nouvel élément d'événement avec <methodname>setEventItem()</methodname>
            entraîne que le nouvel élément sera envoyé à tous les rédacteurs de l'enregistreur.
            Cependant, ceci ne garantit pas que les rédacteurs utilisent réellement l'élément. C'est
            parce que les rédacteurs ne sauront pas quoi faire avec lui à moins qu'un objet
            formateur soit informé du nouvel élément. Veuillez vous reporter à la section sur des
            formateurs pour en apprendre davantage.
        </para>
    </sect2>

    <sect2 id="zend.log.overview.as-errorHandler">
        <title>Log PHP Errors</title>

        <para>
            <classname>Zend_Log</classname> can also be used to log <acronym>PHP</acronym> errors.
            Calling <methodname>registerErrorHandler()</methodname> will add
            <classname>Zend_Log</classname> before the current error handler, and will pass the
            error along as well.
        </para>
        
        <para>
            Zend_Log events from PHP errors have the additional fields matching
            <methodname>handler  ( int $errno  , string $errstr  [, string $errfile  [, int
                $errline  [, array $errcontext  ]]] )</methodname> from <ulink
                url="http://us3.php.net/manual/en/function.set-error-handler.php">set_error_handler</ulink>
        </para>

        <table id="zend.log.overview.as-errorHandler.properties.table-1">
            <title>Additional fields for Zend_Log events from PHP errors</title>

            <tgroup cols="3">
                <thead>
                    <row>
                        <entry>Name</entry>
                        <entry>Error Handler Parameter</entry>
                        <entry>Description</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry>message</entry>
                        <entry>errstr</entry>
                        <entry>Contains the error message, as a string.</entry>
                    </row>

                    <row>
                        <entry>errno</entry>
                        <entry>errno</entry>
                        <entry>Contains the level of the error raised, as an integer.</entry>
                    </row>

                    <row>
                        <entry>file</entry>
                        <entry>errfile</entry>

                        <entry>
                            Contains the filename that the error was raised in, as a string.
                        </entry>
                    </row>

                    <row>
                        <entry>line</entry>
                        <entry>errline</entry>

                        <entry>
                            Contains the line number the error was raised at, as an integer.
                        </entry>
                    </row>

                    <row>
                        <entry>context</entry>
                        <entry>errcontext</entry>

                        <entry>
                            (optional) An array that points to the active symbol table at the point
                            the error occurred. In other words, errcontext  will contain an array of
                            every variable that existed in the scope the error was triggered in.
                            User error handler must not modify error context.
                        </entry>
                    </row>

                </tbody>
            </tgroup>
        </table>
    </sect2>
</sect1>