<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 14978 -->
<!-- Reviewed: no -->
<sect2 id="zend.log.writers.mail">
    <title>In Emails schreiben</title>

    <para>
        <classname>Zend_Log_Writer_Mail</classname> schreibt Logeinträge in eine Email Nachricht indem es
        <classname>Zend_Mail</classname> verwendet. Der Konstruktor von <classname>Zend_Log_Writer_Mail</classname>
        nimmt ein <classname>Zend_Mail</classname> Objekt und ein optionales <classname>Zend_Layout</classname>
        Objekt entgegen.
    </para>

    <para>
        Der primäre Verwendungszweck für <classname>Zend_Log_Writer_Mail</classname> ist es Entwickler,
        System Administratoren, oder jede benötigte Partei über Fehler zu benachrichtigen die
        mit PHP-basierenden Skripten auftreten können. <classname>Zend_Log_Writer_Mail</classname> wurde
        aus der Idee geboren das, wenn irgendetwas fehlschlägt, ein Mensch sofort darüber
        alarmiert werden muß um korrigierende Maßnahmen durchzuführen.
    </para>

    <para>
        Die grundsätzliche Verwendung wird anbei gezeigt:
    </para>

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

$writer = new Zend_Log_Writer_Mail($mail);

// Setzt den Subjekt-Text der verwendet wird; Zusammenfassung der Anzahl der
// Fehler wird der Subjektzeile angefügt bevor die Nachricht gesendet wird.
$writer->setSubjectPrependText('Errors with script foo.php');

// Nur Einträge vom Level Warnung und höher schicken
$writer->addFilter(Zend_Log::WARN);

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

// Irgendetwas schlechtes findet statt!
$log->error('Kann nicht zur datenbank verbinden');

// Wenn der Writer heruntergefahren wird, wird Zend_Mail::send()
// getriggert um ein Email mit allen Logeinträgen zu senden die
// auf oder über dem Filterlevel von Zend_Log liegen
]]></programlisting>

    <para>
        <classname>Zend_Log_Writer_Mail</classname> stellt den Email Body standardmäßig
        als reinen Text dar.
    </para>

    <para>
        Es wird eine Email gesendet die alle Logeinträge enthält die auf oder
        über dem Filterlevel sind. Wenn zum Beispiel, Einträge mit Warnungs-Level
        gesendet werden sollen, und zwei Warnungen und fünf Fehler stattfinden,
        wird das Email in Summe sieben Logeinträge enthalten.
    </para>

    <sect3 id="zend.log.writers.mail.layoutusage">
        <title><classname>Zend_Layout</classname> Verwendung</title>

        <para>
            Eine <classname>Zend_Layout</classname> Instanz kann verwendet werden um den HTML
            Anteil einer Multipart Email zu erstellen. Wenn eine <classname>Zend_Layout</classname>
            Instanz in Verwendung ist, nimmt <classname>Zend_Log_Writer_Mail</classname> an das sie
            verwendet wird um HTML darzustellen und setzt den Body HTML für die
            Nachricht als den <classname>Zend_Layout</classname>-darstellenden Wert.
        </para>

        <para>
            Wenn <classname>Zend_Log_Writer_Mail</classname> mit einer <classname>Zend_Layout</classname>
            Instanz verwendet wird, hat man die Option eine eigene Formatierung zu
            setzen indem die <code>setLayoutFormatter()</code> Methode verwendet wird.
            Wenn kein <classname>Zend_Layout</classname>-spezifischer formatierungs-Eintrag
            spezifiziert wurde, wird der aktuell in Verwendung befindliche Formatierer
            verwendet. Die vollständige Verwendung von <classname>Zend_Layout</classname> mit
            einem eigenen Formatierer wird anbei gezeigt.
        </para>

        <programlisting role="php"><![CDATA[
$mail = new Zend_Mail();
$mail->setFrom('errors@example.org')
     ->addTo('project_developers@example.org');
// Beachte das die Subjektzeile nicht auf der Zend_Mail
// Instanz gesetzt wird!

// Verwende eine einfache Zend_Layout Instanz mit seinen Standardwerten
$layout = new Zend_Layout();

// Erstelle einen Formatierer der den Eintrag in ein Listitem Tag umhüllt
$layoutFormatter = new Zend_Log_Formatter_Simple(
    '<li>' . Zend_Layout::DEFAULT_FORMAT . '</li>'
);

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

// Füge den Formatierer für die Einträge hinzu die mit Zend_Layout
// dargestellt werden
$writer->setLayoutFormatter($layoutFormatter);
$writer->setSubjectPrependText('Fehler im Skript foo.php');
$writer->addFilter(Zend_Log::WARN);

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

// Irgendetwas schlechtes hat stattgefunden!
$log->error('unable to connect to database');

// Wenn der Writer heruntergefahren wird, wird Zend_Mail::send()
// getriggert um ein Email mit allen Logeinträgen zu senden die
// auf oder über dem Filterlevel von Zend_Log liegen
]]></programlisting>
    </sect3>

    <sect3 id="zend.log.writers.mail.dynamicsubjectline">
        <title>Zusammenfassung der Fehlerlevel in der Subjektzeile</title>

        <para>
            Die <code>setSubjectPrependText()</code> Methode kann statt
            <classname>Zend_Mail::setSubject()</classname> verwendet werden um die Subjektzeile
            dynamisch zu schreiben bevor die Email gesendet wird. Wenn, zum Beispiel,
            der dem Subjekt vorangestellte Text "Fehler des Skriptes" heißt, würde das
            Subjekt des Emails das von <classname>Zend_Log_Writer_Mail</classname> mit zwei Warnungen
            und fünf Fehlern erstellt wird "Fehler des Skriptes (warn = 2; error = 5)" sein.
            Wenn kein Subjekttext mit <classname>Zend_Log_Writer_Mail</classname> vorangestellt wird,
            wird die <classname>Zend_Mail</classname> Subjektzeile verwendet, wenn vorhanden.
        </para>
    </sect3>

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

        <para>
            Das Senden von Logeinträgen über Emails kann gefährlich sein. Wenn Fehlerzustände
            vom eigenen Skript falsch behandelt werden, oder man die Fehlerlevel falsch verwendet,
            kann man sich selbst in einer Situation finden in der man Hunderte oder Tausende von
            Emails zu den Empfängern sendet abhängig von der Frequenz der eigenen Fehler.
        </para>

        <para>
            Bis dato bietet <classname>Zend_Log_Writer_Mail</classname> keinen Mechanismus für die
            Limitierung oder andernfalls die Dosierung der Nachrichten. Solche Funktionalitäten,
            können vom Konsumenten, wenn benötigt, selbst implementiert werden.
        </para>

        <para>
            Nochmals, <classname>Zend_Log_Writer_Mail</classname>'s primäres Ziel ist es proaktiv Menschen
            über Fehlerzustände zu benachrichtigen. Wenn diese Fehler zeitgerecht behandelt werden,
            und Sicherheitsmaßnahmen platziert werden um diese Vorbehalte in Zukunft zu
            verhindern, dann kann die Email-basierende Benachtichtigung von Fehlern ein
            nützliches Tool sein.
        </para>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->
