.. _zend.log.writers:

Writers
=======

A Writer is an object that inherits from ``Zend\Log\Writer\AbstractWriter``. A Writer's responsibility is to record
log data to a storage backend.

.. _zend.log.writers.stream:

Writing to Streams
------------------

``Zend\Log\Writer\Stream`` sends log data to a `PHP stream`_.

To write log data to the *PHP* output buffer, use the URL ``php://output``. Alternatively, you can send log data
directly to a stream like ``STDERR`` (``php://stderr``).

.. code-block:: php
   :linenos:

   $writer = new Zend\Log\Writer\Stream('php://output');
   $logger = new Zend\Log\Logger($writer);

   $logger->info('Informational message');

To write data to a file, use one of the `Filesystem URLs`_:

.. code-block:: php
   :linenos:

   $writer = new Zend\Log\Writer\Stream('/path/to/logfile');
   $logger = new Zend\Log\Logger($writer);

   $logger->info('Informational message');

By default, the stream opens in the append mode ("a"). To open it with a different mode, the
``Zend\Log\Writer\Stream`` constructor accepts an optional second parameter for the mode.

The constructor of ``Zend\Log\Writer\Stream`` also accepts an existing stream resource:

.. code-block:: php
   :linenos:

   $stream = @fopen('/path/to/logfile', 'a', false);
   if (! $stream) {
       throw new Exception('Failed to open stream');
   }

   $writer = new Zend\Log\Writer\Stream($stream);
   $logger = new Zend\Log\Logger($writer);

   $logger->info('Informational message');

You cannot specify the mode for existing stream resources. Doing so causes a ``Zend\Log\Exception`` to be thrown.

.. _zend.log.writers.database:

Writing to Databases
--------------------

``Zend\Log\Writer\Db`` writes log information to a database table using ``Zend\Db\Adapter\Adapter``. The
constructor of ``Zend\Log\Writer\Db`` receives a ``Zend\Db\Adapter\Adapter`` instance, a table name, an optional
mapping of event data to database columns, and an optional string contains the character separator for the log
array:

.. code-block:: php
   :linenos:

   $dbconfig = array(
       // Sqlite Configuration
       'driver' => 'Pdo',
       'dsn' => 'sqlite:' . __DIR__ . '/tmp/sqlite.db',
   );
   $db = new Zend\Db\Adapter\Adapter($dbconfig);

   $writer = new Zend\Log\Writer\Db($db, 'log_table_name');
   $logger = new Zend\Log\Logger($writer);

   $logger->info('Informational message');

The example above writes a single row of log data to the database table named 'log_table_name' table. The database
column will be created according to the event array generated by the ``Zend\Log\Logger`` instance.

If we specify the mapping of the events with the database columns the log will store in the database only the
selected fields.

.. code-block:: php
   :linenos:

   $dbconfig = array(
       // Sqlite Configuration
       'driver' => 'Pdo',
       'dsn' => 'sqlite:' . __DIR__ . '/tmp/sqlite.db',
   );
   $db = new Zend\Db\Adapter\Adapter($dbconfig);

   $mapping = array(
       'timestamp' => 'date',
       'priority'  => 'type',
       'message'   => 'event'
   );
   $writer = new Zend\Log\Writer\Db($db, 'log_table_name', $mapping);
   $logger = new Zend\Log\Logger($writer);

   $logger->info('Informational message');

The previous example will store only the log information timestamp, priority and message in the database fields
date, type and event.

The ``Zend\Log\Writer\Db`` has a second optional parameter in the constructor. This parameter is the character
separator for the log events managed by an array. For instance, if we have a log that contains an array extra
fields, this will be translated in 'extra-field', where '-' is the character separator (default) and field is the
subname of the specific extra field.

.. _zend.log.writers.null:

Stubbing Out the Writer
-----------------------

The ``Zend\Log\Writer\Null`` is a stub that does not write log data to anything. It is useful for disabling logging
or stubbing out logging during tests:

.. code-block:: php
   :linenos:

   $writer = new Zend\Log\Writer\Null;
   $logger = new Zend\Log\Logger($writer);

   // goes nowhere
   $logger->info('Informational message');

.. _zend.log.writers.mock:

Testing with the Mock
---------------------

The ``Zend\Log\Writer\Mock`` is a very simple writer that records the raw data it receives in an array exposed as a
public property.

.. code-block:: php
   :linenos:

   $mock = new Zend\Log\Writer\Mock;
   $logger = new Zend\Log\Logger($mock);

   $logger->info('Informational message');

   var_dump($mock->events[0]);

   // Array
   // (
   //    [timestamp] => 2007-04-06T07:16:37-07:00
   //    [message] => Informational message
   //    [priority] => 6
   //    [priorityName] => INFO
   // )

To clear the events logged by the mock, simply set ``$mock->events = array()``.

.. _zend.log.writers.compositing:

Compositing Writers
-------------------

There is no composite Writer object. However, a Log instance can write to any number of Writers. To do this, use
the ``addWriter()`` method:

.. code-block:: php
   :linenos:

   $writer1 = new Zend\Log\Writer\Stream('/path/to/first/logfile');
   $writer2 = new Zend\Log\Writer\Stream('/path/to/second/logfile');

   $logger = new Zend\Log\Logger();
   $logger->addWriter($writer1);
   $logger->addWriter($writer2);

   // goes to both writers
   $logger->info('Informational message');

You can also specify the priority number for each writer to change the order of writing. The priority number is an
integer number passed as second parameter in the ``addWriter()`` method.



.. _`PHP stream`: http://www.php.net/stream
.. _`Filesystem URLs`: http://www.php.net/manual/en/wrappers.php#wrappers.file