guide.txt

来自「视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.」· 文本 代码 · 共 924 行 · 第 1/3 页

=================
 The Log Package
=================

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

:Author:        Jon Parise
:Contact:       [e-mail]
:Date:          $Date: 2004/12/20 01:46:32 $
:Revision:      $Revision: 1.15 $

.. 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/co.php/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://www.phppatterns.com/index.php/article/articleview/49/1/1/

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://www.phppatterns.com/index.php/article/articleview/6/1/1/

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   |
|               |           | parameter is only available when `the factory |
|               |           | method`_ or `the singleton method`_ are used. |
+---------------+-----------+-----------------------------------------------+
| ``$name``     | String    | The name of the log resource to which the     |
|               |           | events will be logged.  The use of this value |
|               |           | is determined by the handler's implementation.|
|               |           | It defaults to an empty string.               |
+---------------+-----------+-----------------------------------------------+
| ``$ident``    | String    | An identification string that will be included|
|               |           | in all log events logged by this handler.     |
|               |           | This value defaults to an empty string and can|
|               |           | be changed at runtime using the ``setIdent()``|
|               |           | method.                                       |
+---------------+-----------+-----------------------------------------------+
| ``$conf``     | Array     | Associative array of key-value pairs that are |
|               |           | used to specify any handler-specific settings.|
+---------------+-----------+-----------------------------------------------+
| ``$level``    | Integer   | Log messages up to and including this level.  |
|               |           | This value defaults to ``PEAR_LOG_DEBUG``.    |
|               |           | See `Log Levels`_ and `Log Level Masks`_.     |
+---------------+-----------+-----------------------------------------------+


Logging an Event
----------------
Events are logged using the ``log()`` method::

    $logger->log('Message', PEAR_LOG_NOTICE);

The first argument contains the log event's message.  Even though the event is
always logged as a string, it is possible to pass an object to the ``log()``
method.  If the object implements a ``getString()`` method, a ``toString()``
method or Zend Engine 2's special ``__toString()`` casting method, it will be
used to determine the object's string representation.  Otherwise, the
`serialized`_ form of the object will be logged.

The second, optional argument specifies the log event's priority.  See the
`Log Levels`_ table for the complete list of priorities.  The default priority
is PEAR_LOG_INFO.

The ``log()`` method will return ``true`` if the event was successfully
logged.

"Shortcut" methods are also available for logging an event at a specific log
level.  See the `Log Levels`_ table for the complete list.

.. _serialized: http://www.php.net/serialize


Log Levels
----------
This table is ordered by highest priority (``PEAR_LOG_EMERG``) to lowest
priority (``PEAR_LOG_DEBUG``).

+-----------------------+---------------+-----------------------------------+
| Level                 | Shortcut      | Description                       |
+=======================+===============+===================================+
| ``PEAR_LOG_EMERG``    | ``emerg()``   | System is unusable                |
+-----------------------+---------------+-----------------------------------+
| ``PEAR_LOG_ALERT``    | ``alert()``   | Immediate action required         |
+-----------------------+---------------+-----------------------------------+
| ``PEAR_LOG_CRIT``     | ``crit()``    | Critical conditions               |
+-----------------------+---------------+-----------------------------------+
| ``PEAR_LOG_ERR``      | ``err()``     | Error conditions                  |
+-----------------------+---------------+-----------------------------------+
| ``PEAR_LOG_WARNING``  | ``warning()`` | Warning conditions                |
+-----------------------+---------------+-----------------------------------+
| ``PEAR_LOG_NOTICE``   | ``notice()``  | Normal but significant            |
+-----------------------+---------------+-----------------------------------+
| ``PEAR_LOG_INFO``     | ``info()``    | Informational                     |
+-----------------------+---------------+-----------------------------------+
| ``PEAR_LOG_DEBUG``    | ``debug()``   | Debug-level messages              |
+-----------------------+---------------+-----------------------------------+


Log Level Masks
---------------
Defining a log level mask allows you to include and/or exclude specific levels
of events from being logged.  The ``$level`` construction parameter (see
`Configuring a Handler`_) uses this mechanism to exclude log events below a
certain priority, and it's possible to define more complex masks once the Log
object has been constructed.

Each priority has a specific mask associated with it.  To compute a priority's
mask, use the static ``Log::MASK()`` method::

    $mask = Log::MASK(PEAR_LOG_INFO);

To compute the mask for all priorities up to a certain level, use the
``Log::UPTO()`` method::

    $mask = Log::UPTO(PEAR_LOG_INFO);

The apply the mask, use the ``setMask()`` method::

    $logger->setMask($mask);

Masks can be be combined using bitwise operations.  To restrict logging to
only those events marked as ``PEAR_LOG_NOTICE`` or ``PEAR_LOG_DEBUG``::

    $mask = Log::MASK(PEAR_LOG_NOTICE) | Log::MASK(PEAR_LOG_DEBUG);
    $logger->setMask($mask);

For convenience, two special masks are predefined: ``PEAR_LOG_NONE`` and
``PEAR_LOG_ALL``.  ``PEAR_LOG_ALL`` is especially useful for exluding only
specific priorities::

    $mask = PEAR_LOG_ALL ^ Log::MASK(PEAR_LOG_NOTICE);
    $logger->setMask($mask);

It is also possible to retrieve and modify a Log object's existing mask::

    $mask = $logger->getMask() | Log::MASK(PEAR_LOG_INFO);
    $logger->setMask($mask);


Flushing Log Events
-------------------
Some log handlers (such as `the console handler`_) support explicit
"buffering".  When buffering is enabled, log events won't actually be written
to the output stream until the handler is closed.  Other handlers (such as
`the file handler`_) support implicit buffering because they use the operating
system's IO routines, which may buffer the output.

It's possible to force these handlers to flush their output, however, by
calling their ``flush()`` method::

    $conf = array('buffering' => true);
    $logger = &Log::singleton('console', '', 'test', $conf);

    for ($i = 0; $i < 10; $i++) {
        $logger->log('This event will be buffered.');
    }

    /* Flush all of the buffered log events. */
    $logger->flush();

    for ($i = 0; $i < 10; $i++) {
        $logger->log('This event will be buffered.');
    }

    /* Implicitly flush the buffered events on close. */
    $logger->close();

At this time, the ``flush()`` method is only implemented by `the console
handler`_, `the file handler`_ and `the mail handler`_.


Standard Log Handlers
=====================

The Console Handler
-------------------
The Console handler outputs log events directly to the console.  It supports
output buffering and configurable string formats.

Configuration
~~~~~~~~~~~~~
+-------------------+-----------+---------------+---------------------------+
| Parameter         | Type      | Default       | Description               |
+===================+===========+===============+===========================+
| ``stream``        | File      | STDOUT_       | The output stream to use. |
+-------------------+-----------+---------------+---------------------------+
| ``buffering``     | Boolean   | False         | Should the output be      |
|                   |           |               | buffered until shutdown?  |
+-------------------+-----------+---------------+---------------------------+
| ``lineFormat``    | String    | ``%1$s %2$s   | Log line format           |
|                   |           | [%3$s] %4$s`` | specification.            |
+-------------------+-----------+---------------+---------------------------+
| ``timeFormat``    | String    | ``%b %d       | Time stamp format         |
|                   |           | %H:%M:%S``    | (for strftime_).          |
+-------------------+-----------+---------------+---------------------------+

.. _STDOUT: http://www.php.net/wrappers.php
.. _strftime: http://www.php.net/strftime

Example
~~~~~~~
::

    $logger = &Log::singleton('console', '', 'ident');
    for ($i = 0; $i < 10; $i++) {
        $logger->log("Log entry $i");
    }