unsupported
 ?÷     =================
 The Log Package
=================

--------------------
 User Documentation
--------------------

:Author:        Jon Parise
:Contact:       jon@php.net

.. contents:: Contents
.. section-numbering::

Using Log Handlers
==================

The Log package is implemented as a framework that supports the notion of
backend-specific log handlers.  The base logging object (defined by the `Log
class`_) is primarily an abstract interface to the currently configured
handler.

A wide variety of handlers are distributed with the Log package, and, should
none of them fit your application's needs, it's easy to `write your own`__.

.. _Log class: http://cvs.php.net/viewvc.cgi/pear/Log/Log.php
__ `Custom Handlers`_

Creating a Log Object
---------------------
There are three ways to create Log objects:

    - Using the ``Log::factory()`` method
    - Using the ``Log::singleton()`` method
    - Direct instantiation

The Factory Method
~~~~~~~~~~~~~~~~~~
The ``Log::factory()`` method implements the `Factory Pattern`_.  It allows
for the parameterized construction of concrete Log instances at runtime.  The
first parameter to the ``Log::factory()`` method indicates the name of the
concrete handler to create.  The rest of the parameters will be passed on to
the handler's constructor (see `Configuring a Handler`_ below).

The new ``Log`` instance is returned by reference.

::

    require_once 'Log.php';

    $console = Log::factory('console', '', 'TEST');
    $console->log('Logging to the console.');

    $file = Log::factory('file', 'out.log', 'TEST');
    $file->log('Logging to out.log.');

.. _Factory Pattern: http://wikipedia.org/wiki/Factory_method_pattern

The Singleton Method
~~~~~~~~~~~~~~~~~~~~
The ``Log::singleton()`` method implements the `Singleton Pattern`_.  The
singleton pattern ensures that only a single instance of a given log type and
configuration is ever created.  This has two benefits: first, it prevents
duplicate ``Log`` instances from being constructed, and, second, it gives all
of your code access to the same ``Log`` instance.  The latter is especially
important when logging to files because only a single file handler will need
to be managed.

The ``Log::singleton()`` method's parameters match the ``Log::factory()``
method.  The new ``Log`` instance is returned by reference.

::

    require_once 'Log.php';

    /* Same construction parameters */
    $a = Log::singleton('console', '', 'TEST');
    $b = Log::singleton('console', '', 'TEST');

    if ($a === $b) {
        echo '$a and $b point to the same Log instance.' . "\n";
    }

    /* Different construction parameters */
    $c = Log::singleton('console', '', 'TEST1');
    $d = Log::singleton('console', '', 'TEST2');

    if ($c !== $d) {
        echo '$c and $d point to different Log instances.' . "\n";
    }

.. _Singleton Pattern: http://wikipedia.org/wiki/Singleton_pattern

Direct Instantiation
~~~~~~~~~~~~~~~~~~~~
It is also possible to directly instantiate concrete ``Log`` handler
instances.  However, this method is **not recommended** because it creates a
tighter coupling between your application code and the Log package than is
necessary.  Use of `the factory method`_ or `the singleton method`_ is
preferred.


Configuring a Handler
---------------------
A log handler's configuration is determined by the arguments used in its
construction.  Here's an overview of those parameters::

    /* Using the factory method ... */
    Log::factory($handler, $name, $ident, $conf, $maxLevel);

    /* Using the singleton method ... */
    Log::singleton($handler, $name, $ident, $conf, $maxLevel);

    /* Using direct instantiation ... */
    new Log_handler($name, $ident, $conf, $maxLevel);

+---------------+-----------+-----------------------------------------------+
| Parameter     | Type      | Description                                   |
+===============+===========+===============================================+
| ``$handler``  | String    | The type of Log handler to construct.  This   |
|               |           | p