repo_zf1/documentation/manual/ja/module_specs/Zend_Log-Formatters.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 15103 -->
<sect1 id="zend.log.formatters">
  <title>フォーマッタ</title>
  <para>
    フォーマッタの役割は、<code>event</code> 配列からイベントの内容を受け取り、
    それを文字列としてフォーマットして出力することです。
  </para>

  <para>
    ライターによっては行指向ではないものもあります。そのような場合はフォーマッタは使用できません。
    たとえばデータベースライターなどがその例で、
    これはイベントの項目を直接データベースのカラムに書き出します。
    フォーマッタをサポートできないライターに対してフォーマッタを設定しようとすると、
    例外がスローされます。
  </para>

  <sect2 id="zend.log.formatters.simple">
    <title>単純なフォーマット</title>
    <para>
      <classname>Zend_Log_Formatter_Simple</classname> はデフォルトのフォーマッタです。
      これは、何もフォーマッタを指定しなかった場合に自動的に設定されます。
      デフォルトの設定は、次のようになります。

      <programlisting role="php"><![CDATA[
$format = '%timestamp% %priorityName% (%priority%): %message%' . PHP_EOL;
$formatter = new Zend_Log_Formatter_Simple($format);
]]>
      </programlisting>
    </para>

    <para>
      フォーマッタを個々のライターオブジェクトに対して設定するには、ライターの
      <code>setFormatter()</code> メソッドを使用します。

      <programlisting role="php"><![CDATA[
$writer = new Zend_Log_Writer_Stream('php://output');
$formatter = new Zend_Log_Formatter_Simple('hello %message%' . PHP_EOL);
$writer->setFormatter($formatter);

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

$logger->info('there');

// "hello there" と出力します
]]>
      </programlisting>
    </para>

    <para>
      <classname>Zend_Log_Formatter_Simple</classname> のコンストラクタには、
      パラメータとして書式指定文字列を渡すことができます。
      この文字列には、キーをパーセント記号で囲んだもの
      (例. <code>%message%</code>) を含めます。
      書式指定文字列には、イベントデータの配列の任意のキーを含めることができます。
      デフォルトのキーを取得するには、<classname>Zend_Log_Formatter_Simple</classname>
      の定数 DEFAULT_FORMAT を使用します。
    </para>
  </sect2>

  <sect2 id="zend.log.formatters.xml">
    <title>XML へのフォーマット</title>
    <para>
      <classname>Zend_Log_Formatter_Xml</classname> は、ログのデータを XML 文字列に変換します。
      デフォルトでは、イベントデータ配列のすべての項目を自動的に記録します。

      <programlisting role="php"><![CDATA[
$writer = new Zend_Log_Writer_Stream('php://output');
$formatter = new Zend_Log_Formatter_Xml();
$writer->setFormatter($formatter);

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

$logger->info('通知メッセージ');
]]>
      </programlisting>
    </para>

    <para>
      上のコードの出力は、次のような XML になります (可読性を確保するため空白を補っています)。

      <programlisting role="xml"><![CDATA[
<logEntry>
  <timestamp>2007-04-06T07:24:37-07:00</timestamp>
  <message>通知メッセージ</message>
  <priority>6</priority>
  <priorityName>INFO</priorityName>
</logEntry>
]]>
</programlisting>
    </para>

    <para>
      ルート要素を変更したり、XML の要素名とイベントデータ配列の項目名の対応を指定したりすることも可能です。
      <classname>Zend_Log_Formatter_Xml</classname> のコンストラクタの最初のパラメータには、
      ルート要素の名前を指定します。また、
      二番目のパラメータには要素名の対応を表す連想配列を指定します。

      <programlisting role="php"><![CDATA[
$writer = new Zend_Log_Writer_Stream('php://output');
$formatter = new Zend_Log_Formatter_Xml('log',
                                        array('msg' => 'message',
                                              'level' => 'priorityName')
                                       );
$writer->setFormatter($formatter);

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

$logger->info('通知メッセージ');
]]>
      </programlisting>

      上のコードは、ルート要素の名前をデフォルトの
      <code>logEntry</code> から <code>log</code> に変更します。また、要素名
      <code>msg</code> をイベントデータの項目 <code>message</code> に対応させます。
      出力結果は次のようになります。

      <programlisting role="xml"><![CDATA[
<log>
  <msg>通知メッセージ</msg>
  <level>INFO</level>
</log>
]]>
</programlisting>
    </para>

  </sect2>
</sect1>