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

<!-- EN-Revision: 13840 -->
<sect1 id="zend.log.formatters">
    <title>Formateurs (mise en forme)</title>

    <para>Un formateur est un objet qui est responsable de prendre un tableau <code>event</code> décrivant un événement
    de log et produisant une ligne de log formatée sous la forme d'un une chaîne.</para>

    <para>Quelques rédacteurs ("Writers") ne fonctionnent pas en terme de ligne et ne peuvent pas utiliser un formateur.
    Un exemple est le rédacteur de base de données, qui insère les items d'événement directement en colonnes de base de
    données. Pour les rédacteurs qui ne peuvent pas supporter un formateur, une exception est levée si vous essayez
    d'affecter un formateur.</para>

    <sect2 id="zend.log.formatters.simple">
        <title>Formatage simple</title>

        <para><classname>Zend_Log_Formatter_Simple</classname> est le formateur par défaut. Il est configuré automatiquement quand
        vous n'indiquez aucun formateur. La configuration par défaut est équivalente à ce qui suit : <programlisting
        role="php"><![CDATA[
$format = '%timestamp% %priorityName% (%priority%): %message%' . PHP_EOL;
$formatter = new Zend_Log_Formatter_Simple($format);
]]></programlisting></para>

        <para>Un formateur est affecté à un objet individuel de rédacteur en utilisant la méthode
        <code>setFormatter()</code> du rédacteur : <programlisting role="php"><![CDATA[
$redacteur = new Zend_Log_Writer_Stream('php://output');
$formateur = new Zend_Log_Formatter_Simple('Bonjour %message%' . PHP_EOL);
$redacteur->setFormatter($formateur);

$logger = new Zend_Log();
$logger->addWriter($redacteur);

$logger->info('Monde');

// affiche "Bonjour Monde"
]]></programlisting></para>

        <para>Le constructeur de <classname>Zend_Log_Formatter_Simple</classname> accepte un paramètre unique : la chaîne de
        formatage. Cette chaîne contient des clés entourées par le signe pourcentage (par exemple %message%). La chaîne
        de formatage peut contenir n'importe quelle clé du tableau de données d'événement. Vous pouvez récupérer les
        clés par défaut en utilisant la constante DEFAULT_FORMAT de <classname>Zend_Log_Formatter_Simple</classname>.</para>
    </sect2>

    <sect2 id="zend.log.formatters.xml">
        <title>Formater vers le XML</title>

        <para><classname>Zend_Log_Formatter_Xml</classname> formate des données de log dans des chaînes de type XML. Par défaut,
        il note automatiquement tout le tableau de données d'événements : <programlisting role="php"><![CDATA[
$redacteur = new Zend_Log_Writer_Stream('php://output');
$formateur = new Zend_Log_Formatter_Xml();
$redacteur->setFormatter($formateur);

$logger = new Zend_Log();
$logger->addWriter($redacteur);

$logger->info("Message d'information");
]]></programlisting></para>

        <para>Le code ci-dessus affiche le XML suivant (des espaces supplémentaires sont ajoutés pour la clarté) :
        <programlisting role="xml"><![CDATA[
<logEntry>
  <timestamp>2007-04-06T07:24:37-07:00</timestamp>
  <message>Message d'information</message>
  <priority>6</priority>
  <priorityName>INFO</priorityName>
</logEntry>
]]></programlisting></para>

        <para>Il est possible d'adapter l'élément racine comme indiquent faire correspondre les éléments XML au tableau
        de données d'évènements. Le constructeur de <classname>Zend_Log_Formatter_Xml</classname> accepte une chaîne avec le nom
        de l'élément racine comme premier paramètre et un tableau associatif avec les éléments de correspondance comme
        deuxième paramètre : <programlisting role="php"><![CDATA[
$redacteur = new Zend_Log_Writer_Stream('php://output');
$formateur = new Zend_Log_Formatter_Xml('log',
                                        array('msg' => 'message',
                                              'niveau' => 'priorityName'));
$redacteur->setFormatter($formateur);

$logger = new Zend_Log();
$logger->addWriter($redacteur);

$logger->info("Message d'information");
]]></programlisting> Le code ci-dessus change l'élément racine par défaut de
        <code>logEntry</code> en <code>log</code>. Il fait correspondre également les éléments <code>msg</code> au
        <code>message</code> de l'item de donnée d'événement. Ceci a comme conséquence l'affichage suivant :
        <programlisting role="xml"><![CDATA[
<log>
  <msg>Message d'information</msg>
  <niveau>INFO</niveau>
</log>
]]></programlisting></para>
    </sect2>
</sect1>