repo_zf1Php7/documentation/manual/en/module_specs/Zend_Log-Writers-Mail.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.log.writers.mail">
    <title>Writing to Email</title>

    <para>
        <classname>Zend_Log_Writer_Mail</classname> writes log entries in an email message
        by using <classname>Zend_Mail</classname>. The <classname>Zend_Log_Writer_Mail</classname>
        constructor takes a <classname>Zend_Mail</classname> object, and an optional
        <classname>Zend_Layout</classname> object.
    </para>

    <para>
        The primary use case for <classname>Zend_Log_Writer_Mail</classname> is notifying
        developers, systems administrators, or any concerned parties of errors
        that might be occurring with <acronym>PHP</acronym>-based scripts.
        <classname>Zend_Log_Writer_Mail</classname> was born out of the idea that if
        something is broken, a human being needs to be alerted of it immediately
        so they can take corrective action.
    </para>

    <para>
        Basic usage is outlined below:
    </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);

// Set subject text for use; summary of number of errors is appended to the
// subject line before sending the message.
$writer->setSubjectPrependText('Errors with script foo.php');

// Only email warning level entries and higher.
$writer->addFilter(Zend_Log::WARN);

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

// Something bad happened!
$log->error('unable to connect to database');

// On writer shutdown, Zend_Mail::send() is triggered to send an email with
// all log entries at or above the Zend_Log filter level.
]]></programlisting>

    <para>
        <classname>Zend_Log_Writer_Mail</classname> will render the email body as plain
        text by default.
    </para>

    <para>
        One email is sent containing all log entries at or above the filter
        level. For example, if warning-level entries an up are to be emailed,
        and two warnings and five errors occur, the resulting email will contain
        a total of seven log entries.
    </para>

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

        <para>
            A <classname>Zend_Layout</classname> instance may be used to generate the
            <acronym>HTML</acronym> portion of a multipart email. If a
            <classname>Zend_Layout</classname> instance is in use,
            <classname>Zend_Log_Writer_Mail</classname> assumes that it is being used to render
            <acronym>HTML</acronym> and sets the body <acronym>HTML</acronym> for the message as
            the <classname>Zend_Layout</classname>-rendered value.
        </para>

        <para>
            When using <classname>Zend_Log_Writer_Mail</classname> with a
            <classname>Zend_Layout</classname> instance, you have the option to set a
            custom formatter by using the <methodname>setLayoutFormatter()</methodname>
            method. If no <classname>Zend_Layout</classname>-specific entry formatter was
            specified, the formatter currently in use will be used. Full usage
            of <classname>Zend_Layout</classname> with a custom formatter is outlined
            below.
        </para>

        <programlisting language="php"><![CDATA[
$mail = new Zend_Mail();
$mail->setFrom('errors@example.org')
     ->addTo('project_developers@example.org');
// Note that a subject line is not being set on the Zend_Mail instance!

// Use a simple Zend_Layout instance with its defaults.
$layout = new Zend_Layout();

// Create a formatter that wraps the entry in a listitem tag.
$layoutFormatter = new Zend_Log_Formatter_Simple(
    '<li>' . Zend_Log_Formatter_Simple::DEFAULT_FORMAT . '</li>'
);

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

// Apply the formatter for entries as rendered with Zend_Layout.
$writer->setLayoutFormatter($layoutFormatter);
$writer->setSubjectPrependText('Errors with script foo.php');
$writer->addFilter(Zend_Log::WARN);

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

// Something bad happened!
$log->error('unable to connect to database');

// On writer shutdown, Zend_Mail::send() is triggered to send an email with
// all log entries at or above the Zend_Log filter level. The email will
// contain both plain text and HTML parts.
]]></programlisting>
    </sect3>

    <sect3 id="zend.log.writers.mail.dynamicsubjectline">
        <title>Subject Line Error Level Summary</title>

        <para>
            The <methodname>setSubjectPrependText()</methodname> method may be used in place
            of <methodname>Zend_Mail::setSubject()</methodname> to have the email subject
            line dynamically written before the email is sent. For example, if
            the subject prepend text reads "Errors from script", the subject of
            an email generated by <classname>Zend_Log_Writer_Mail</classname> with two
            warnings and five errors would be "Errors from script (warn = 2;
            error = 5)". If subject prepend text is not in use via
            <classname>Zend_Log_Writer_Mail</classname>, the <classname>Zend_Mail</classname>
            subject line, if any, is used.
        </para>
    </sect3>

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

        <para>
            Sending log entries via email can be dangerous. If error conditions
            are being improperly handled by your script, or if you're misusing
            the error levels, you might find yourself in a situation where you
            are sending hundreds or thousands of emails to the recipients
            depending on the frequency of your errors.
        </para>

        <para>
            At this time, <classname>Zend_Log_Writer_Mail</classname> does not provide any
            mechanism for throttling or otherwise batching up the messages.
            Such functionality should be implemented by the consumer if
            necessary.
        </para>

        <para>
            Again, <classname>Zend_Log_Writer_Mail</classname>'s primary goal is to
            proactively notify a human being of error conditions. If those
            errors are being handled in a timely fashion, and safeguards are
            being put in place to prevent those circumstances in the future,
            then email-based notification of errors can be a valuable tool.
        </para>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->