PhpRiot
Become Zend Certified

Prepare for the ZCE exam using our quizzes (web or iPad/iPhone). More info...


When you're ready get 7.5% off your exam voucher using voucher CJQNOV23 at the Zend Store

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:

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

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

Zend Framework