# Writing to Email

`Zend_Log_Writer_Mail` writes log entries in an email message by using `Zend_Mail`. The `Zend_Log_Writer_Mail` constructor takes a `Zend_Mail` object, and an optional `Zend_Layout` object.

The primary use case for `Zend_Log_Writer_Mail` is notifying developers, systems administrators, or any concerned parties of errors that might be occurring with PHP-based scripts. `Zend_Log_Writer_Mail` 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.

Basic usage is outlined below:

    $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.

`Zend_Log_Writer_Mail` will render the email body as plain text by default.

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.

## Zend_Layout Usage

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

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

    $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.

## Subject Line Error Level Summary

The `setSubjectPrependText()` method may be used in place of `Zend_Mail::setSubject()` 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 `Zend_Log_Writer_Mail` with two warnings and five errors would be "Errors from script (warn = 2; error = 5)". If subject prepend text is not in use via `Zend_Log_Writer_Mail`, the `Zend_Mail` subject line, if any, is used.

## Caveats

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.

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

Again, `Zend_Log_Writer_Mail`'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.