# Formatters

A Formatter is an object that is responsible for taking an event array describing a log event and outputting a string with a formatted log line.

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.

## Simple Formatting

Zend_Log_Formatter_Simple is the default formatter. It is configured automatically when you specify no formatter. The default configuration is equivalent to the following:

    $format = '%timestamp% %priorityName% (%priority%): %message%' . PHP_EOL;
    $formatter = new Zend_Log_Formatter_Simple($format);

A formatter is set on an individual Writer object using the Writer's setFormatter() method:

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

The constructor of Zend_Log_Formatter_Simple accepts a single parameter: the format string. This string contains keys surrounded by percent signs (e.g. `%message%`). 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 Zend_Log_Formatter_Simple.

## Formatting to XML

Zend_Log_Formatter_Xml formats log data into XML strings. By default, it automatically logs all items in the event data array:

    $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');

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

    <logEntry>
      <timestamp>2007-04-06T07:24:37-07:00</timestamp>
      <message>informational message</message>
      <priority>6</priority>
      <priorityName>INFO</priorityName>
    </logEntry>

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

    $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');

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

    <log>
      <msg>informational message</msg>
      <level>INFO</level>
    </log>