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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.log.writers.mail">
   4     <title>Writing to Email</title>
   5
   6     <para>
   7         <classname>Zend_Log_Writer_Mail</classname> writes log entries in an email message
   8         by using <classname>Zend_Mail</classname>. The <classname>Zend_Log_Writer_Mail</classname>
   9         constructor takes a <classname>Zend_Mail</classname> object, and an optional
  10         <classname>Zend_Layout</classname> object.
  11     </para>
  12
  13     <para>
  14         The primary use case for <classname>Zend_Log_Writer_Mail</classname> is notifying
  15         developers, systems administrators, or any concerned parties of errors
  16         that might be occurring with <acronym>PHP</acronym>-based scripts.
  17         <classname>Zend_Log_Writer_Mail</classname> was born out of the idea that if
  18         something is broken, a human being needs to be alerted of it immediately
  19         so they can take corrective action.
  20     </para>
  21
  22     <para>
  23         Basic usage is outlined below:
  24     </para>
  25
  26     <programlisting language="php"><![CDATA[
  27 $mail = new Zend_Mail();
  28 $mail->setFrom('errors@example.org')
  29      ->addTo('project_developers@example.org');
  30
  31 $writer = new Zend_Log_Writer_Mail($mail);
  32
  33 // Set subject text for use; summary of number of errors is appended to the
  34 // subject line before sending the message.
  35 $writer->setSubjectPrependText('Errors with script foo.php');
  36
  37 // Only email warning level entries and higher.
  38 $writer->addFilter(Zend_Log::WARN);
  39
  40 $log = new Zend_Log();
  41 $log->addWriter($writer);
  42
  43 // Something bad happened!
  44 $log->error('unable to connect to database');
  45
  46 // On writer shutdown, Zend_Mail::send() is triggered to send an email with
  47 // all log entries at or above the Zend_Log filter level.
  48 ]]></programlisting>
  49
  50     <para>
  51         <classname>Zend_Log_Writer_Mail</classname> will render the email body as plain
  52         text by default.
  53     </para>
  54
  55     <para>
  56         One email is sent containing all log entries at or above the filter
  57         level. For example, if warning-level entries an up are to be emailed,
  58         and two warnings and five errors occur, the resulting email will contain
  59         a total of seven log entries.
  60     </para>
  61
  62     <sect3 id="zend.log.writers.mail.layoutusage">
  63         <title>Zend_Layout Usage</title>
  64
  65         <para>
  66             A <classname>Zend_Layout</classname> instance may be used to generate the
  67             <acronym>HTML</acronym> portion of a multipart email. If a
  68             <classname>Zend_Layout</classname> instance is in use,
  69             <classname>Zend_Log_Writer_Mail</classname> assumes that it is being used to render
  70             <acronym>HTML</acronym> and sets the body <acronym>HTML</acronym> for the message as
  71             the <classname>Zend_Layout</classname>-rendered value.
  72         </para>
  73
  74         <para>
  75             When using <classname>Zend_Log_Writer_Mail</classname> with a
  76             <classname>Zend_Layout</classname> instance, you have the option to set a
  77             custom formatter by using the <methodname>setLayoutFormatter()</methodname>
  78             method. If no <classname>Zend_Layout</classname>-specific entry formatter was
  79             specified, the formatter currently in use will be used. Full usage
  80             of <classname>Zend_Layout</classname> with a custom formatter is outlined
  81             below.
  82         </para>
  83
  84         <programlisting language="php"><![CDATA[
  85 $mail = new Zend_Mail();
  86 $mail->setFrom('errors@example.org')
  87      ->addTo('project_developers@example.org');
  88 // Note that a subject line is not being set on the Zend_Mail instance!
  89
  90 // Use a simple Zend_Layout instance with its defaults.
  91 $layout = new Zend_Layout();
  92
  93 // Create a formatter that wraps the entry in a listitem tag.
  94 $layoutFormatter = new Zend_Log_Formatter_Simple(
  95     '<li>' . Zend_Log_Formatter_Simple::DEFAULT_FORMAT . '</li>'
  96 );
  97
  98 $writer = new Zend_Log_Writer_Mail($mail, $layout);
  99
 100 // Apply the formatter for entries as rendered with Zend_Layout.
 101 $writer->setLayoutFormatter($layoutFormatter);
 102 $writer->setSubjectPrependText('Errors with script foo.php');
 103 $writer->addFilter(Zend_Log::WARN);
 104
 105 $log = new Zend_Log();
 106 $log->addWriter($writer);
 107
 108 // Something bad happened!
 109 $log->error('unable to connect to database');
 110
 111 // On writer shutdown, Zend_Mail::send() is triggered to send an email with
 112 // all log entries at or above the Zend_Log filter level. The email will
 113 // contain both plain text and HTML parts.
 114 ]]></programlisting>
 115     </sect3>
 116
 117     <sect3 id="zend.log.writers.mail.dynamicsubjectline">
 118         <title>Subject Line Error Level Summary</title>
 119
 120         <para>
 121             The <methodname>setSubjectPrependText()</methodname> method may be used in place
 122             of <methodname>Zend_Mail::setSubject()</methodname> to have the email subject
 123             line dynamically written before the email is sent. For example, if
 124             the subject prepend text reads "Errors from script", the subject of
 125             an email generated by <classname>Zend_Log_Writer_Mail</classname> with two
 126             warnings and five errors would be "Errors from script (warn = 2;
 127             error = 5)". If subject prepend text is not in use via
 128             <classname>Zend_Log_Writer_Mail</classname>, the <classname>Zend_Mail</classname>
 129             subject line, if any, is used.
 130         </para>
 131     </sect3>
 132
 133     <sect3 id="zend.log.writers.mail.caveats">
 134         <title>Caveats</title>
 135
 136         <para>
 137             Sending log entries via email can be dangerous. If error conditions
 138             are being improperly handled by your script, or if you're misusing
 139             the error levels, you might find yourself in a situation where you
 140             are sending hundreds or thousands of emails to the recipients
 141             depending on the frequency of your errors.
 142         </para>
 143
 144         <para>
 145             At this time, <classname>Zend_Log_Writer_Mail</classname> does not provide any
 146             mechanism for throttling or otherwise batching up the messages.
 147             Such functionality should be implemented by the consumer if
 148             necessary.
 149         </para>
 150
 151         <para>
 152             Again, <classname>Zend_Log_Writer_Mail</classname>'s primary goal is to
 153             proactively notify a human being of error conditions. If those
 154             errors are being handled in a timely fashion, and safeguards are
 155             being put in place to prevent those circumstances in the future,
 156             then email-based notification of errors can be a valuable tool.
 157         </para>
 158     </sect3>
 159 </sect2>
 160 <!--
 161 vim:se ts=4 sw=4 et:
 162 -->