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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 17875 -->
   4 <sect2 id="zend.log.writers.mail">
   5     <title>Email への書き込み</title>
   6
   7     <para>
   8         <classname>Zend_Log_Writer_Mail</classname> は、
   9         <classname>Zend_Mail</classname> を使ってログエントリをメールのメッセージに書き出します。
  10         <classname>Zend_Log_Writer_Mail</classname> のコンストラクタは
  11         <classname>Zend_Mail</classname> オブジェクトを受け取り、
  12         またオプションで <classname>Zend_Layout</classname> オブジェクトを受け取ります。
  13     </para>
  14
  15     <para>
  16         <classname>Zend_Log_Writer_Mail</classname> の主な使い道は、
  17         開発者やシステム管理者など関係者に対して
  18         <acronym>PHP</acronym> スクリプトで発生したエラーを通知することです。
  19         「何か問題がおこったら、すぐに人間に通知しないとね。
  20         そうすればすぐに適切な対応ができるわけだから」そんなアイデアを元に
  21         <classname>Zend_Log_Writer_Mail</classname> が誕生しました。
  22     </para>
  23
  24     <para>
  25         基本的な使い方は以下のとおりです。
  26     </para>
  27
  28     <programlisting language="php"><![CDATA[
  29 $mail = new Zend_Mail();
  30 $mail->setFrom('errors@example.org')
  31      ->addTo('project_developers@example.org');
  32
  33 $writer = new Zend_Log_Writer_Mail($mail);
  34
  35 // 件名に使用するテキストを設定します。実際にメッセージを送信する前に、
  36 // 発生したエラー数がこの件名に付け加えられます
  37 $writer->setSubjectPrependText('Errors with script foo.php');
  38
  39 // 警告レベル以上の場合にのみメールを送信します
  40 $writer->addFilter(Zend_Log::WARN);
  41
  42 $log = new Zend_Log();
  43 $log->addWriter($writer);
  44
  45 // なにかが起こりました！
  46 $log->error('unable to connect to database');
  47
  48 // ライターの処理が終了すると Zend_Mail::send() が立ち上がり、
  49 // 上の Zend_Log フィルタレベル以上のすべてのログメッセージが送信されます
  50 ]]></programlisting>
  51
  52     <para>
  53         <classname>Zend_Log_Writer_Mail</classname> は、デフォルトで
  54         メールの本文をプレーンテキスト形式でレンダリングします。
  55     </para>
  56
  57     <para>
  58         指定したフィルタレベル以上のすべてのログエントリが、
  59         ひとつのメールにまとめて送られます。たとえば、
  60         警告レベル以上を送信するよう設定しているときに
  61         2 つの警告と 5 つのエラーが発生したら、
  62         メールには 7 つのログエントリが含まれることになります。
  63     </para>
  64
  65     <sect3 id="zend.log.writers.mail.layoutusage">
  66         <title>Zend_Layout の使用法</title>
  67
  68         <para>
  69             <classname>Zend_Layout</classname> のインスタンスを使用して、
  70             マルチパートメールの HTML 部を作成することができます。
  71             <classname>Zend_Layout</classname> のインスタンスが用いられた場合、
  72             <classname>Zend_Log_Writer_Mail</classname> は HTML をレンダリングするものとみなし、
  73             <classname>Zend_Layout</classname> がレンダリングした値をメッセージの本文
  74             HTML として設定します。
  75         </para>
  76
  77         <para>
  78             <classname>Zend_Log_Writer_Mail</classname> で
  79             <classname>Zend_Layout</classname> のインスタンスを使う場合には、
  80             <methodname>setLayoutFormatter()</methodname> メソッドで独自のフォーマッタを指定することができます。
  81             <classname>Zend_Layout</classname> 用のエントリフォーマッタを指定しなかった場合は、
  82             現在使用中のものをそのまま使います。
  83             <classname>Zend_Layout</classname> で独自のフォーマッタを使用する方法を以下に示します。
  84         </para>
  85
  86         <programlisting language="php"><![CDATA[
  87 $mail = new Zend_Mail();
  88 $mail->setFrom('errors@example.org')
  89      ->addTo('project_developers@example.org');
  90 // 件名は Zend_Mail のインスタンスには設定していないことに注意しましょう!
  91
  92 // シンプルに、デフォルトの Zend_Layout のインスタンスを使用します
  93 $layout = new Zend_Layout();
  94
  95 // エントリを li タグで囲むフォーマッタを作成します
  96 $layoutFormatter = new Zend_Log_Formatter_Simple(
  97     '<li>' . Zend_Log_Formatter_Simple::DEFAULT_FORMAT . '</li>'
  98 );
  99
 100 $writer = new Zend_Log_Writer_Mail($mail, $layout);
 101
 102 // Zend_Layout でレンダリングするための、エントリのフォーマッタを適用します
 103 $writer->setLayoutFormatter($layoutFormatter);
 104 $writer->setSubjectPrependText('Errors with script foo.php');
 105 $writer->addFilter(Zend_Log::WARN);
 106
 107 $log = new Zend_Log();
 108 $log->addWriter($writer);
 109
 110 // なにかが起こりました！
 111 $log->error('unable to connect to database');
 112
 113 // ライターの処理が終了すると Zend_Mail::send() が立ち上がり、
 114 // 上の Zend_Log フィルタレベル以上のすべてのログメッセージが送信されます
 115 // メールは、プレーンテキストと HTML パートの両方を含む形式になります
 116 ]]></programlisting>
 117     </sect3>
 118
 119     <sect3 id="zend.log.writers.mail.dynamicsubjectline">
 120         <title>件名でのエラーの概要</title>
 121
 122         <para>
 123             <methodname>setSubjectPrependText()</methodname> メソッドを
 124             <methodname>Zend_Mail::setSubject()</methodname> のかわりに使用すると、
 125             メールを送信する直前に件名を動的に書き込むことができます。たとえば、
 126             件名のテキストが "Errors from script" だとすると、
 127             2 つの警告と 5 つのエラーが発生した場合に <classname>Zend_Log_Writer_Mail</classname>
 128             が作成するメールの件名は "Errors from script (warn = 2;
 129             error = 5)" となります。<classname>Zend_Log_Writer_Mail</classname>
 130             で件名のテキストを設定しなかった場合、もし <classname>Zend_Mail</classname>
 131             で設定されていればそれを使用します。
 132         </para>
 133     </sect3>
 134
 135     <sect3 id="zend.log.writers.mail.caveats">
 136         <title>警告</title>
 137
 138         <para>
 139             ログエントリをメールでおくるのは危険なこともあります。
 140             スクリプト内でのエラー条件の処理が不適切だったり
 141             エラーレベルの使用法を間違えたりすると、
 142             エラーの発生頻度によっては何百通何千通ものメールを送信してしまう可能性があります。
 143         </para>
 144
 145         <para>
 146             現時点では、<classname>Zend_Log_Writer_Mail</classname>
 147             にはメッセージを抑制したりひとつにまとめたりする機能はありません。
 148             そのような機能が必要な場合は自前で実装する必要があります。
 149         </para>
 150
 151         <para>
 152             もう一度言いますが、<classname>Zend_Log_Writer_Mail</classname>
 153             の第一の目標は、人間に向けてエラーの情報を積極的に伝えることです。
 154             これらのエラーがタイミングよく処理され、
 155             このような状況が避けられるような機能が実装されたときには、
 156             メールによるエラー通知は便利な道具となることでしょう。
 157         </para>
 158     </sect3>
 159 </sect2>
 160 <!--
 161 vim:se ts=4 sw=4 et:
 162 -->