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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.log.formatters">
  <title>Formatters</title>
  <para>
    A Formatter is an object that is responsible for taking an <code>event</code> array
    describing a log event and outputting a string with a formatted log line.
  </para>

  <para>
    Some Writers are not line-oriented and cannot use a Formatter. An example is the
    Database Writer, which inserts the event items directly into database columns. For
    Writers that cannot support a Formatter, an exception is thrown if you attempt to
    set a Formatter.
  </para>

  <sect2 id="zend.log.formatters.simple">
    <title>Simple Formatting</title>
    <para>
      <classname>Zend_Log_Formatter_Simple</classname> is the default formatter. It is configured
      automatically when you specify no formatter. The default configuration is equivalent
      to the following:

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

    <para>
      A formatter is set on an individual Writer object using the Writer's
      <methodname>setFormatter()</methodname> method:

      <programlisting language="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');

// outputs "hello there"
]]></programlisting>
    </para>

    <para>
      The constructor of <classname>Zend_Log_Formatter_Simple</classname> accepts a single
      parameter: the format string. This string contains keys surrounded by
      percent signs (e.g. <code>%message%</code>). The format string may
      contain any key from the event data array.
      You can retrieve the default keys by using the DEFAULT_FORMAT constant from
      <classname>Zend_Log_Formatter_Simple</classname>.
    </para>
  </sect2>

  <sect2 id="zend.log.formatters.xml">
    <title>Formatting to XML</title>
    <para>
      <classname>Zend_Log_Formatter_Xml</classname> formats log data into XML strings.
      By default, it automatically logs all items in the event data array:

      <programlisting language="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('informational message');
]]></programlisting>
    </para>

    <para>
      The code above outputs the following XML (space added for clarity):

      <programlisting language="xml"><![CDATA[
<logEntry>
  <timestamp>2007-04-06T07:24:37-07:00</timestamp>
  <message>informational message</message>
  <priority>6</priority>
  <priorityName>INFO</priorityName>
</logEntry>
]]></programlisting>
    </para>

    <para>
      It's possible to customize the root element as well as specify a mapping
      of XML elements to the items in the event data array. The constructor
      of <classname>Zend_Log_Formatter_Xml</classname> accepts a string with the name of
      the root element as the first parameter and an associative array with
      the element mapping as the second parameter:

      <programlisting language="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('informational message');
]]></programlisting>

      The code above changes the root element from its default of
      <code>logEntry</code> to <code>log</code>. It also maps the element
      <code>msg</code> to the event data item <code>message</code>. This
      results in the following output:

      <programlisting language="xml"><![CDATA[
<log>
  <msg>informational message</msg>
  <level>INFO</level>
</log>
]]></programlisting>
    </para>

  </sect2>
</sect1>