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 <property>event</property> 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:
        </para>

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

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

        <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>
            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. <command>%message%</command>). 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
            <acronym>XML</acronym> strings. By default, it automatically logs all items in the event
            data array:
        </para>

        <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>
            The code above outputs the following <acronym>XML</acronym> (space added for clarity):
        </para>

        <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>
            It's possible to customize the root element as well as specify a mapping
            of <acronym>XML</acronym> 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:
        </para>

        <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>

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

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