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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect2 id="zend.log.writers.mail">
    <title>Email への書き込み</title>

    <para>
        <classname>Zend_Log_Writer_Mail</classname> は、
        <classname>Zend_Mail</classname> を使ってログエントリをメールのメッセージに書き出します。
        <classname>Zend_Log_Writer_Mail</classname> のコンストラクタは
        <classname>Zend_Mail</classname> オブジェクトを受け取り、
        またオプションで <classname>Zend_Layout</classname> オブジェクトを受け取ります。
    </para>

    <para>
        <classname>Zend_Log_Writer_Mail</classname> の主な使い道は、
        開発者やシステム管理者など関係者に対して
        <acronym>PHP</acronym> スクリプトで発生したエラーを通知することです。
        「何か問題がおこったら、すぐに人間に通知しないとね。
        そうすればすぐに適切な対応ができるわけだから」そんなアイデアを元に
        <classname>Zend_Log_Writer_Mail</classname> が誕生しました。
    </para>

    <para>
        基本的な使い方は以下のとおりです。
    </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);

// 件名に使用するテキストを設定します。実際にメッセージを送信する前に、
// 発生したエラー数がこの件名に付け加えられます
$writer->setSubjectPrependText('Errors with script foo.php');

// 警告レベル以上の場合にのみメールを送信します
$writer->addFilter(Zend_Log::WARN);

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

// なにかが起こりました！
$log->error('unable to connect to database');

// ライターの処理が終了すると Zend_Mail::send() が立ち上がり、
// 上の Zend_Log フィルタレベル以上のすべてのログメッセージが送信されます
]]></programlisting>

    <para>
        <classname>Zend_Log_Writer_Mail</classname> は、デフォルトで
        メールの本文をプレーンテキスト形式でレンダリングします。
    </para>

    <para>
        指定したフィルタレベル以上のすべてのログエントリが、
        ひとつのメールにまとめて送られます。たとえば、
        警告レベル以上を送信するよう設定しているときに
        2 つの警告と 5 つのエラーが発生したら、
        メールには 7 つのログエントリが含まれることになります。
    </para>

    <sect3 id="zend.log.writers.mail.layoutusage">
        <title>Zend_Layout の使用法</title>

        <para>
            <classname>Zend_Layout</classname> のインスタンスを使用して、
            マルチパートメールの <acronym>HTML</acronym> 部を作成できます。
            <classname>Zend_Layout</classname> のインスタンスが用いられた場合、
            <classname>Zend_Log_Writer_Mail</classname> は <acronym>HTML</acronym> をレンダリングするものとみなし、
            <classname>Zend_Layout</classname> がレンダリングした値をメッセージの本文
            <acronym>HTML</acronym> として設定します。
        </para>

        <para>
            <classname>Zend_Log_Writer_Mail</classname> で
            <classname>Zend_Layout</classname> のインスタンスを使う場合には、
            <methodname>setLayoutFormatter()</methodname> メソッドで独自のフォーマッタを指定できます。
            <classname>Zend_Layout</classname> 用のエントリフォーマッタを指定しなかった場合は、
            現在使用中のものをそのまま使います。
            <classname>Zend_Layout</classname> で独自のフォーマッタを使用する方法を以下に示します。
        </para>

        <programlisting language="php"><![CDATA[
$mail = new Zend_Mail();
$mail->setFrom('errors@example.org')
     ->addTo('project_developers@example.org');
// 件名は Zend_Mail のインスタンスには設定していないことに注意しましょう!

// シンプルに、デフォルトの Zend_Layout のインスタンスを使用します
$layout = new Zend_Layout();

// エントリを li タグで囲むフォーマッタを作成します
$layoutFormatter = new Zend_Log_Formatter_Simple(
    '<li>' . Zend_Log_Formatter_Simple::DEFAULT_FORMAT . '</li>'
);

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

// Zend_Layout でレンダリングするための、エントリのフォーマッタを適用します
$writer->setLayoutFormatter($layoutFormatter);
$writer->setSubjectPrependText('Errors with script foo.php');
$writer->addFilter(Zend_Log::WARN);

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

// なにかが起こりました！
$log->error('unable to connect to database');

// ライターの処理が終了すると Zend_Mail::send() が立ち上がり、
// 上の Zend_Log フィルタレベル以上のすべてのログメッセージが送信されます
// メールは、プレーンテキストと HTML パートの両方を含む形式になります
]]></programlisting>
    </sect3>

    <sect3 id="zend.log.writers.mail.dynamicsubjectline">
        <title>件名でのエラーの概要</title>

        <para>
            <methodname>setSubjectPrependText()</methodname> メソッドを
            <methodname>Zend_Mail::setSubject()</methodname> のかわりに使用すると、
            メールを送信する直前に件名を動的に書き込むことができます。たとえば、
            件名のテキストが "Errors from script" だとすると、
            2 つの警告と 5 つのエラーが発生した場合に <classname>Zend_Log_Writer_Mail</classname>
            が作成するメールの件名は "Errors from script (warn = 2;
            error = 5)" となります。<classname>Zend_Log_Writer_Mail</classname>
            で件名のテキストを設定しなかった場合、もし <classname>Zend_Mail</classname>
            で設定されていればそれを使用します。
        </para>
    </sect3>

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

        <para>
            ログエントリをメールでおくるのは危険なこともあります。
            スクリプト内でのエラー条件の処理が不適切だったり
            エラーレベルの使用法を間違えたりすると、
            エラーの発生頻度によっては何百通何千通ものメールを送信してしまう可能性があります。
        </para>

        <para>
            現時点では、<classname>Zend_Log_Writer_Mail</classname>
            にはメッセージを抑制したりひとつにまとめたりする機能はありません。
            そのような機能が必要な場合は自前で実装する必要があります。
        </para>

        <para>
            もう一度言いますが、<classname>Zend_Log_Writer_Mail</classname>
            の第一の目標は、人間に向けてエラーの情報を積極的に伝えることです。
            これらのエラーがタイミングよく処理され、
            このような状況が避けられるような機能が実装されたときには、
            メールによるエラー通知は便利な道具となることでしょう。
        </para>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->