repo_zf1/documentation/manual/fr/module_specs/Zend_Log-Writers-Mail.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect2 id="zend.log.writers.mail">
    <title>Écrire vers un courriel</title>

    <para>
        <classname>Zend_Log_Writer_Mail</classname> va écrire les entrées du log dans un message
        courriel en utilisant <classname>Zend_Mail</classname>. Le constructeur de
        <classname>Zend_Log_Writer_Mail</classname> requière un objet
        <classname>Zend_Mail</classname> et optionnellement un objet
        <classname>Zend_Layout</classname>.
    </para>

    <para>
        Le cas d'utilisation principal de <classname>Zend_Log_Writer_Mail</classname> est
        la notification les développeurs, les administrateurs ou toute personne concernée,
        d'une erreur qui peut survenir dans des scripts.
        <classname>Zend_Log_Writer_Mail</classname> a été crée avec l'idée que si quelque chose
        ne tourne pas rond, une intervention humaine est nécessaire.
    </para>

    <para>
        Voici un exemple d'utilisation basique&#160;:
    </para>

    <programlisting language="php"><![CDATA[
$mail = new Zend_Mail();
$mail->setFrom('errors@example.org')
     ->addTo('project_developers@example.org');

$writer = new Zend_Log_Writer_Mail($mail);

// Ecrit le sujet. Un résumé des erreurs est ajouté à la suite
$writer->setSubjectPrependText('Errors with script foo.php');

// Limite uniquement au niveau Warning ou supérieur
$writer->addFilter(Zend_Log::WARN);

$log = new Zend_Log();
$log->addWriter($writer);

// Essai
$log->error('unable to connect to database');

// A la fermeture, Zend_Mail::send() est inviqué et concernera
// tous les logs passés dans le filtre.
]]></programlisting>

    <para>
        <classname>Zend_Log_Writer_Mail</classname> utilisera un corps de message
        en texte plein (plain text) par défaut.
    </para>

    <para>
        Le filtre est géré. Par exemple si le filtre est réglé sur Warnings, et que
        2 évènements warnings et 5 évènements erreurs se produisent, alors 7
        évènements seront envoyés.
    </para>

    <sect3 id="zend.log.writers.mail.layoutusage">
        <title>Utilisation avec Zend_Layout</title>

        <para>
            Une instance de <classname>Zend_Layout</classname> peut être utilisée pour générer
            du HTML qui fera partie du courriel multipart. Si <classname>Zend_Layout</classname>
            est utilisé, <classname>Zend_Log_Writer_Mail</classname> considérera que le corps HTML
            du message sera la valeur du rendu de <classname>Zend_Layout</classname>.
        </para>

        <para>
            En utilisant <classname>Zend_Log_Writer_Mail</classname> avec un objet
            <classname>Zend_Layout</classname> vous pouvez utiliser un formateur
            personnalisé grâce à <methodname>setLayoutFormatter()</methodname>. Si aucun formateur spécifique
            <classname>Zend_Layout</classname> n'est indiqué, le formateur en cours d'utilisation
            sera appelé. Voici un exemple&#160;:
        </para>

        <programlisting language="php"><![CDATA[
$mail = new Zend_Mail();
$mail->setFrom('errors@example.org')
     ->addTo('project_developers@example.org');
// Nous ne spécifions pas le sujet du message dans l'objet Zend_Mail !

// Utilisons un simple objet Zend_Layout
$layout = new Zend_Layout();

// Créons un formateur à base de listes
$layoutFormatter = new Zend_Log_Formatter_Simple(
    '<li>' . Zend_Log_Formatter_Simple::DEFAULT_FORMAT . '</li>'
);

$writer = new Zend_Log_Writer_Mail($mail, $layout);

// Appliquons le formateur sur le rendu de Zend_Layout.
$writer->setLayoutFormatter($layoutFormatter);
$writer->setSubjectPrependText('Errors with script foo.php');
$writer->addFilter(Zend_Log::WARN);

$log = new Zend_Log();
$log->addWriter($writer);

// essai
$log->error('unable to connect to database');

// A la fermeture, Zend_Mail::send() est inviqué et concernera
// tous les logs passés dans le filtre.
// l'email contiendra une partie "plain text", et une partie HTML
]]></programlisting>
    </sect3>

    <sect3 id="zend.log.writers.mail.dynamicsubjectline">
        <title>Ligne du sujet dynamique</title>

        <para>
            La méthode <methodname>setSubjectPrependText()</methodname> est utilisée à la place de
            <methodname>Zend_Mail::setSubject()</methodname> pour que la ligne de sujet dans le courriel
            soit générée dynamiquement avant l'envoi de ce dernier. Par exemple, si le texte indiqué
            est "Erreurs depuis ce script", le sujet du courriel généré par
            <classname>Zend_Log_Writer_Mail</classname> avec 2 warnings et 5 errors sera alors
            "Erreurs depuis ce script (warn = 2; error = 5)". Si le sujet n'est pas indiqué
            via <classname>Zend_Log_Writer_Mail</classname>, la ligne de sujet
            de <classname>Zend_Mail</classname>, si il y en a une, sera utilisée.
        </para>
    </sect3>

    <sect3 id="zend.log.writers.mail.caveats">
        <title>Attention</title>

        <para>
            Envoyer des rapports d'erreurs par emails peut être dangereux.
            Si votre système de surveillance d'erreurs n'est pas correct ou a un problème,
            vous risquez de vous retrouver inondé de tonnes d'emails en provenance de
            votre application.
        </para>

        <para>
            A l'heure actuelle, il n'existe dans <classname>Zend_Log_Writer_Mail</classname>
            aucun système de limitation ou de contrôle du nombre ou de la fréquence d'envoi
            des emails. Si vous nécessitez un tel système, vous devrez l'implémenter vous-même.
        </para>

        <para>
            Encore une fois, l'unique but de <classname>Zend_Log_Writer_Mail</classname>
            est la notification d'un humain au sujet d'une erreur. Si ce système est
            clairement contrôlé, alors il peut devenir un avantage très appréciable.
        </para>
    </sect3>
</sect2>