guide.txt

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

Configuration
~~~~~~~~~~~~~
+-------------------+-----------+---------------+---------------------------+
| Parameter         | Type      | Default       | Description               |
+===================+===========+===============+===========================+
| ``filename``      | String    | '' `(empty)`  | Path to an Sqlite         |
|                   |           |               | database. |required|      |
+-------------------+-----------+---------------+---------------------------+
| ``mode``          | Integer   | 0666          | Octal mode used to open   |
|                   |           |               | the database.             |
+-------------------+-----------+---------------+---------------------------+
| ``persistent``    | Boolean   | false         | Use a persistent          |
|                   |           |               | connection.               |
+-------------------+-----------+---------------+---------------------------+

An already opened database connection can also be passed as parameter instead
of the above configuration.  In this case, closing the database connection is
up to the user.

.. _native PHP sqlite functions: http://www.php.net/sqlite
.. _ATTACH: http://www.sqlite.org/lang.html#attach

Examples
~~~~~~~~
Using a configuration to create a new database connection::

    $conf = array('filename' => 'log.db', 'mode' => 0666, 'persistent' => true);
    $logger =& Log::factory('sqlite', 'log_table', 'ident', $conf);
    $logger->log('logging an event', PEAR_LOG_WARNING);

Using an existing connection::

    $db = sqlite_open('log.db', 0666, $error);
    $logger =& Log::factory('sqlite', 'log_table', 'ident', $db);
    $logger->log('logging an event', PEAR_LOG_WARNING);
    sqlite_close($db);


The Syslog Handler
------------------
The Syslog handler sends log events to the system logging service (syslog on
Unix-like environments or the Event Log on Windows systems).  The events are
sent using PHP's `syslog()`_ function.

Facilities
~~~~~~~~~~
+-------------------+-------------------------------------------------------+
| Constant          | Category Description                                  |
+===================+=======================================================+
| ``LOG_AUTH``      | Security / authorization messages; ``LOG_AUTHPRIV`` is|
|                   | preferred on systems where it is defined.             |
+-------------------+-------------------------------------------------------+
| ``LOG_AUTHPRIV``  | Private security / authorization messages             |
+-------------------+-------------------------------------------------------+
| ``LOG_CRON``      | Clock daemon (``cron`` and ``at``)                    |
+-------------------+-------------------------------------------------------+
| ``LOG_DAEMON``    | System daemon processes                               |
+-------------------+-------------------------------------------------------+
| ``LOG_KERN``      | Kernel messages                                       |
+-------------------+-------------------------------------------------------+
| ``LOG_LOCAL0`` .. | Reserved for local use; **not** available under       |
| ``LOG_LOCAL7``    | Windows.                                              |
+-------------------+-------------------------------------------------------+
| ``LOG_LPR``       | Printer subsystem                                     |
+-------------------+-------------------------------------------------------+
| ``LOG_MAIL``      | Mail subsystem                                        |
+-------------------+-------------------------------------------------------+
| ``LOG_NEWS``      | USENET news subsystem                                 |
+-------------------+-------------------------------------------------------+
| ``LOG_SYSLOG``    | Internal syslog messages                              |
+-------------------+-------------------------------------------------------+
| ``LOG_USER``      | Generic user-level messages                           |
+-------------------+-------------------------------------------------------+
| ``LOG_UUCP``      | UUCP subsystem                                        |
+-------------------+-------------------------------------------------------+

.. _syslog(): http://www.php.net/syslog

Example
~~~~~~~
::

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


The Window Handler
------------------
The Window handler sends log events to a separate browser window.  The
original idea for this handler was inspired by Craig Davis' Zend.com article
entitled `"JavaScript Power PHP Debugging"`_.

Configuration
~~~~~~~~~~~~~
+-------------------+-----------+---------------+---------------------------+
| Parameter         | Type      | Default       | Description               |
+===================+===========+===============+===========================+
| ``title``         | String    | ``Log Output  | The title of the output   |
|                   |           | Window``      | window.                   |
+-------------------+-----------+---------------+---------------------------+
| ``colors``        | Array     | `ROY G BIV`_  | Mapping of log priorities |
|                   |           | (high to low) | to colors.                |
+-------------------+-----------+---------------+---------------------------+

.. _"JavaScript Power PHP Debugging": http://www.zend.com/zend/tut/tutorial-DebugLib.php
.. _ROY G BIV: http://www.cis.rit.edu/

Example
~~~~~~~
::

    $conf = array('title' => 'Sample Log Output');
    $logger = &Log::singleton('win', 'LogWindow', 'ident', $conf);
    for ($i = 0; $i < 10; $i++) {
        $logger->log("Log entry $i");
    }


Composite Handlers
==================
It is often useful to log events to multiple handlers.  The Log package
provides a compositing system that marks this task trivial.

Start by creating the individual log handlers::

    $console = &Log::singleton('console', '', 'TEST');
    $file = &Log::singleton('file', 'out.log', 'TEST');

Then, construct a composite handler and add the individual handlers as
children of the composite::

    $composite = &Log::singleton('composite');
    $composite->addChild($console);
    $composite->addChild($file);

The composite handler implements the standard ``Log`` interface so you can use
it just like any of the other handlers::

    $composite->log('This event will be logged to both handlers.');

Children can be removed from the composite when they're not longer needed::

    $composite->removeChild($file);


Log Observers
=============
Log observers provide an implementation of the `observer pattern`_.  In the
content of the Log package, they provide a mechanism by which you can examine
(i.e. observe) each event as it is logged.  This allows the implementation of
special behavior based on the contents of a log event.  For example, the
observer code could send an alert email if a log event contained the string
``PANIC``.

Creating a log observer involves implementing a subclass of the
``Log_observer`` class.  The subclass must override the base class's
``notify()`` method.  This method is passed a hash containing the event's
priority and event.  The subclass's implementation is free to act upon this
information in any way it likes.

Log observers are attached to ``Log`` instances via the ``attach()`` method::

    $observer = &Log_observer::factory('yourType');
    $logger->attach($observer);

Observers can be detached using the ``detach()`` method::

    $logger->detach($observer);

At this time, no concrete ``Log_observer`` implementations are distributed
with the Log package.

.. _observer pattern: http://phppatterns.com/index.php/article/articleview/27/1/1/


Logging From Standard Error Handlers
====================================

Logging PHP Errors
------------------
PHP's default error handler can be overridden using the `set_error_handler()`_
function.  The custom error handling function can use a global Log instance to
log the PHP errors.

**Note:** Fatal PHP errors cannot be handled by a custom error handler at this
time.

::

    function errorHandler($code, $message, $file, $line)
    {
        global $logger;

        /* Map the PHP error to a Log priority. */
        switch ($code) {
        case E_WARNING:
        case E_USER_WARNING:
            $priority = PEAR_LOG_WARNING;
            break;
        case E_NOTICE:
        case E_USER_NOTICE:
            $priority = PEAR_LOG_NOTICE;
            break;
        case E_ERROR:
        case E_USER_ERROR:
            $priority = PEAR_LOG_ERR;
            break;
        default:
            $priotity = PEAR_LOG_INFO;
        }

        $logger->log($message . ' in ' . $file . ' at line ' . $line,
                     $priority);
    }

    set_error_handler('errorHandler');
    trigger_error('This is an information log message.', E_USER_NOTICE);

.. _set_error_handler(): http://www.php.net/set_error_handler

Logging PEAR Errors
-------------------
The Log package can be used with `PEAR::setErrorHandling()`_'s
``PEAR_ERROR_CALLBACK`` mechanism by writing an error handling function that
uses a global Log instance.  Here's an example::

    function errorHandler($error)
    {
        global $logger;

        $message = $error->getMessage();

        if (!empty($error->backtrace[1]['file'])) {
            $message .= ' (' . $error->backtrace[1]['file'];
            if (!empty($error->backtrace[1]['line'])) {
                $message .= ' at line ' . $error->backtrace[1]['line'];
            }
            $message .= ')';
        }

        $logger->log($message, $error->code);
    }

    PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, 'errorHandler');
    PEAR::raiseError('This is an information log message.', PEAR_LOG_INFO);

.. _PEAR::setErrorHandling(): http://pear.php.net/manual/en/core.pear.pear.seterrorhandling.php


Custom Handlers
===============
There are times when the standard handlers aren't a perfect match for your
needs.  In those situations, the solution might be to write a custom handler.

Using a Custom Handler
----------------------
Using a custom Log handler is very simple.  Once written (see `Writing New
Handlers`_ and `Extending Existing Handlers`_ below), you have the choice of
placing the file in your PEAR installation's main ``Log/`` directory (usually
something like ``/usr/local/lib/php/Log`` or ``C:\php\pear\Log``), where it
can be found and use by any PHP application on the system, or placing the file
somewhere in your application's local hierarchy and including it before the
the custom Log object is constructed.

Method 1: Handler in the Standard Location
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After copying the handler file to your PEAR installation's ``Log/`` directory,
simply treat the handler as if it were part of the standard distributed.  If
your handler is named ``custom`` (and therefore implemented by a class named
``Log_custom``)::

    require_once 'Log.php';

    $logger = &Log::factory('custom', '', 'CUSTOM');


Method 2: Handler in a Custom Location
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you prefer storing your handler in your application's local hierarchy,
you'll need to include that file before you can create a Log instance based on
it.

::

    require_once 'Log.php';
    require_once 'LocalHandlers/custom.php';

    $logger = &Log::factory('custom', '', 'CUSTOM');


Writing New Handlers
--------------------

TODO

Extending Existing Handlers
---------------------------

TODO


.. |required| replace:: **[required]**

.. vim: tabstop=4 shiftwidth=4 softtabstop=4 expandtab textwidth=78 ft=rst: