/library/3rdParty/Log/docs/guide.txt
Plain Text | 1282 lines | 1017 code | 265 blank | 0 comment | 0 complexity | a7639430902ae1c883efa9167365d8fc MD5 | raw file
Possible License(s): BSD-3-Clause, LGPL-2.0, MIT
Large files files are truncated, but you can click here to view the full file
- =================
- The Log Package
- =================
- --------------------
- User Documentation
- --------------------
- :Author: Jon Parise
- :Contact: jon@php.net
- :Date: $Date: 2008/11/19 05:12:26 $
- :Revision: $Revision: 1.41 $
- .. 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 |
- | | | 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, and including, a certain level,
- use the ``Log::MAX()`` static method::
- $mask = Log::MAX(PEAR_LOG_INFO);
- To compute the mask for all priorities greater than or equal to a certain
- level, use the ``Log::MIN()`` static method::
- $mask = Log::MIN(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 excluding 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);
- Log Line Format
- ---------------
- Most log handlers support configurable line formats. The following is a list
- of special tokens that will be expanded at runtime with contextual information
- related to the log event. Each token has an alternate shorthand notation, as
- well.
- +------------------+-----------+--------------------------------------------+
- | Token | Alternate | Description |
- +==================+===========+============================================+
- | ``%{timestamp}`` | ``%1$s`` | Timestamp. This is often configurable. |
- +------------------+-----------+--------------------------------------------+
- | ``%{ident}`` | ``%2$s`` | The log handler's identification string. |
- +------------------+-----------+--------------------------------------------+
- | ``%{priority}`` | ``%3$s`` | The log event's priority. |
- +------------------+-----------+--------------------------------------------+
- | ``%{message}`` | ``%4$s`` | The log event's message text. |
- +------------------+-----------+--------------------------------------------+
- | ``%{file}`` | ``%5$s`` | The full filename of the logging file. |
- +------------------+-----------+--------------------------------------------+
- | ``%{line}`` | ``%6$s`` | The line number on which the event occured.|
- +------------------+-----------+--------------------------------------------+
- | ``%{function}`` | ``%7$s`` | The function from which the event occurred.|
- +------------------+-----------+--------------------------------------------+
- | ``%{class}`` | ``%8$s`` | The class in which the event occurred. |
- +------------------+-----------+--------------------------------------------+
- 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`_, `the Firebug 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");
- }
- The Display Handler
- -------------------
- The Display handler simply prints the log events back to the browser. It
- respects the ``error_prepend_string`` and ``error_append_string`` `error
- handling values`_ and is useful when `logging from standard error handlers`_.
- Configuration
- ~~~~~~~~~~~~~
- +-------------------+-----------+---------------+---------------------------+
- | Parameter | Type | Default | Description |
- +===================+===========+===============+===========================+
- | ``lineFormat`` | String | ``<b>%3$s</b>:| `Log line format`_ |
- | | | %4$s`` | specification. |
- +-------------------+-----------+---------------+---------------------------+
- | ``timeFormat`` | String | ``%b %d | Time stamp format |
- | | | %H:%M:%S`` | (for strftime_). |
- +-------------------+-----------+---------------+---------------------------+
- | ``error_prepend`` | String | PHP INI value | This string will be |
- | | | | prepended to the line |
- | | | | format. |
- +-------------------+-----------+---------------+---------------------------+
- | ``error_append`` | String | PHP INI value | This string will be |
- | | | | appended to the line |
- | | | | format. |
- +-------------------+-----------+---------------+---------------------------+
- | ``linebreak`` | String | ``<br />\n`` | This string is used to |
- | | | | represent a line break. |
- +-------------------+-----------+---------------+---------------------------+
- .. _error handling values: http://www.php.net/errorfunc
- Example
- ~~~~~~~
- ::
- $conf = array('error_prepend' => '<font color="#ff0000"><tt>',
- 'error_append' => '</tt></font>');
- $logger = &Log::singleton('display', '', '', $conf, PEAR_LOG_DEBUG);
- for ($i = 0; $i < 10; $i++) {
- $logger->log("Log entry $i");
- }
- The Error_Log Handler
- ---------------------
- The Error_Log handler sends log events to PHP's `error_log()`_ function.
- Configuration
- ~~~~~~~~~~~~~
- +-------------------+-----------+---------------+---------------------------+
- | Parameter | Type | Default | Description |
- +===================+===========+===============+===========================+
- | ``destination`` | String | '' `(empty)` | Optional destination value|
- | | | | for `error_log()`_. See |
- | | | | `Error_Log Types`_ for |
- | | | | more details. |
- +-------------------+-----------+---------------+---------------------------+
- | ``extra_headers`` | String | '' `(empty)` | Additional headers to pass|
- | | | | to the `mail()`_ function |
- | | | | when the |
- | | | | ``PEAR_LOG_TYPE_MAIL`` |
- | | | | type is specified. |
- +-------------------+-----------+---------------+---------------------------+
- | ``lineFormat`` | String | ``%2$s: %4$s``| `Log line format`_ |
- | | | | specification. |
- +-------------------+-----------+---------------+---------------------------+
- | ``timeFormat`` | String | ``%b %d | Time stamp format |
- | | | %H:%M:%S`` | (for strftime_). |
- +-------------------+-----------+---------------+---------------------------+
- Error_Log Types
- ~~~~~~~~~~~~~~~
- All of the available log types are detailed in the `error_log()`_ section of
- the PHP manual. For your convenience, the Log package also defines the
- following constants that can be used for the ``$name`` handler construction
- parameter.
- +---------------------------+-----------------------------------------------+
- | Constant | Description |
- +===========================+===============================================+
- | ``PEAR_LOG_TYPE_SYSTEM`` | Log events are sent to PHP's system logger, |
- | | which uses the operating system's logging |
- | | mechanism or a file (depending on the value |
- | | of the `error_log configuration directive`_). |
- +---------------------------+-----------------------------------------------+
- | ``PEAR_LOG_TYPE_MAIL`` | Log events are sent via email to the address |
- | | specified in the ``destination`` value. |
- +---------------------------+-----------------------------------------------+
- | ``PEAR_LOG_TYPE_DEBUG`` | Log events are sent through PHP's debugging |
- | | connection. This will only work if |
- | | `remote debugging`_ has been enabled. The |
- | | ``destination`` value is used to specify the |
- | | host name or IP address of the target socket. |
- +---------------------------+-----------------------------------------------+
- | ``PEAR_LOG_TYPE_FILE`` | Log events will be appended to the file named |
- | | by the ``destination`` value. |
- +---------------------------+-----------------------------------------------+
- .. _error_log(): http://www.php.net/error_log
- .. _mail(): http://www.php.net/mail
- .. _error_log configuration directive: http://www.php.net/errorfunc#ini.error-log
- .. _remote debugging: http://www.php.net/install.configure#install.configure.enable-debugger
- Example
- ~~~~~~~
- ::
- $logger = &Log::singleton('error_log', PEAR_LOG_TYPE_SYSTEM, 'ident');
- for ($i = 0; $i < 10; $i++) {
- $logger->log("Log entry $i");
- }
- The File Handler
- ----------------
- The File handler writes log events to a text file using configurable string
- formats.
- Configuration
- ~~~~~~~~~~~~~
- +-------------------+-----------+---------------+---------------------------+
- | Parameter | Type | Default | Description |
- +===================+===========+===============+===========================+
- | ``append`` | Boolean | True | Should new log entries be |
- | | | | append to an existing log |
- | | | | file, or should the a new |
- | | | | log file overwrite an |
- | | | | existing one? |
- +-------------------+-----------+---------------+---------------------------+
- | ``locking`` | Boolean | False | Should advisory file |
- | | | | locking (using flock_) be |
- | | | | used? |
- +-------------------+-----------+---------------+---------------------------+
- | ``mode`` | Integer | 0644 | Octal representation of |
- | | | | the log file's permissions|
- | | | | mode. |
- +-------------------+-----------+---------------+---------------------------+
- | ``dirmode`` | Integer | 0755 | Octal representation of |
- | | | | the file permission mode |
- | | | | that will be used when |
- | | | | creating directories that |
- | | | | do not already exist. |
- +-------------------+-----------+---------------+---------------------------+
- | ``eol`` | String | OS default | The end-on-line character |
- | | | | sequence. |
- +-------------------+-----------+---------------+---------------------------+
- | ``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_). |
- +-------------------+-----------+---------------+---------------------------+
- .. _flock: http://www.php.net/flock
- .. _strftime: http://www.php.net/strftime
- The file handler will only attempt to set the ``mode`` value if it was
- responsible for creating the file.
- Example
- ~~~~~~~
- ::
- $conf = array('mode' => 0600, 'timeFormat' => '%X %x');
- $logger = &Log::singleton('file', 'out.log', 'ident', $conf);
- for ($i = 0; $i < 10; $i++) {
- $logger->log("Log entry $i");
- }
- The Firebug Handler
- -------------------
- The Firebug handler outputs log events to the Firebug_ console. It supports
- output buffering and configurable string formats.
- Configuration
- ~~~~~~~~~~~~~
- +-------------------+-----------+---------------+---------------------------+
- | Parameter | Type | Default | Description |
- +===================+===========+===============+===========================+
- | ``buffering`` | Boolean | False | Should the output be |
- | | | | buffered until shutdown? |
- +-------------------+-----------+---------------+---------------------------+
- | ``lineFormat`` | String | ``%2$s [%3$s] | `Log line format`_ |
- | | | %4$s`` | specification. |
- +-------------------+-----------+---------------+---------------------------+
- | ``timeFormat`` | String | ``%b %d | Time stamp format |
- | | | %H:%M:%S`` | (for strftime_). |
- +-------------------+-----------+---------------+---------------------------+
- .. _Firebug: http://www.getfirebug.com/
- .. _strftime: http://www.php.net/strftime
- Example
- ~~~~~~~
- ::
- $logger = &Log::singleton('firebug', '', 'ident');
- for ($i = 0; $i < 10; $i++) {
- $logger->log("Log entry $i");
- }
- The Mail Handler
- ----------------
- The Mail handler aggregates a session's log events and sends them in the body
- of an email message using either the `PEAR Mail`_ package or PHP's native
- `mail()`_ function.
- If an empty ``mailBackend`` value is specified, the `mail()`_ function will be
- used instead of the `PEAR Mail`_ package.
- Multiple recipients can be specified by separating their email addresses with
- commas in the ``$name`` construction parameter.
- Configuration
- ~~~~~~~~~~~~~
- +-------------------+-----------+---------------+---------------------------+
- | Parameter | Type | Default | Description |
- +===================+===========+===============+===========================+
- | ``from`` | String | sendmail_from | Value for the message's |
- | | | INI value | ``From:`` header. |
- +-------------------+-----------+---------------+---------------------------+
- | ``subject`` | String | ``[Log_mail] | Value for the message's |
- | | | Log message`` | ``Subject:`` header. |
- +-------------------+-----------+---------------+---------------------------+
- | ``preamble`` | String | `` `(empty)` | Preamble for the message. |
- +-------------------+-----------+---------------+---------------------------+
- | ``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_). |
- +-------------------+-----------+---------------+---------------------------+
- | ``mailBackend`` | String | `` `(empty)` | Name of the Mail package |
- | | | | backend to use. |
- +-------------------+-----------+---------------+---------------------------+
- | ``mailParams`` | Array | `(empty)` | Array of parameters that |
- | | | | will be passed to the |
- | | | | Mail package backend. |
- +-------------------+-----------+---------------+---------------------------+
- .. _PEAR Mail: http://pear.php.net/package/Mail
- .. _mail(): http://www.php.net/mail
- Example
- ~~~~~~~
- ::
- $conf = array('subject' => 'Important Log Events');
- $logger = &Log::singleton('mail', 'webmaster@example.com', 'ident', $conf);
- for ($i = 0; $i < 10; $i++) {
- $logger->log("Log entry $i");
- }
- The MDB2 Handler
- ----------------
- The MDB2 handler is similar to `the SQL (DB) handler`_, but instead of using
- the PEAR DB package, it uses the `MDB2 database abstraction package`_.
- Configuration
- ~~~~~~~~~~~~~
- +-------------------+-----------+---------------+---------------------------+
- | Parameter | Type | Default | Description |
- +===================+===========+===============+===========================+
- | ``dsn`` | Mixed | '' `(empty)` | A `Data Source Name`_. |
- | | | | |required| |
- +-------------------+-----------+---------------+---------------------------+
- | ``options`` | Array | ``persistent``| An array of `MDB2`_ |
- | | | | options. |
- +-------------------+-----------+---------------+---------------------------+
- | ``db`` | Object | NULL | An existing `MDB2`_ |
- | | | | object. If specified, |
- | | | | this object will be used, |
- | | | | and ``dsn`` will be |
- | | | | ignored. |
- +-------------------+-----------+---------------+---------------------------+
- | ``sequence`` | String | ``log_id`` | The name of the sequence |
- | | | | to use when generating |
- | | | | unique event IDs. Under |
- | | | | many databases, this will |
- | | | | be used as the name of |
- | | | | the sequence table. |
- +-------------------+-----------+---------------+---------------------------+
- | ``identLimit`` | Integer | 16 | The maximum length of the |
- | | | | ``ident`` string. |
- | | | | **Changing this value may |
- | | | | require updates to the SQL|
- | | | | schema, as well.** |
- +-------------------+-----------+---------------+---------------------------+
- | ``singleton`` | Boolean | false | Is true, use a singleton |
- | | | | database object using |
- | | | | `MDB2::singleton()`_. |
- +-------------------+-----------+---------------+---------------------------+
- .. _MDB2: http://pear.php.net/package/MDB2
- .. _MDB2 database abstraction package: MDB2_
- .. _MDB2::singleton(): http://pear.php.net/package/MDB2/docs/latest/MDB2/MDB2.html#methodsingleton
- The Null Handler
- ----------------
- The Null handler simply consumes log events (akin to sending them to
- ``/dev/null``). `Log level masks`_ are respected, and the event will still be
- sent to any registered `log observers`_.
- Example
- ~~~~~~~
- ::
- $logger = &Log::singleton('null');
- for ($i = 0; $i < 10; $i++) {
- $logger->log("Log entry $i");
- }
- The SQL (DB) Handler
- --------------------
- The SQL handler sends log events to a database using `PEAR's DB abstraction
- layer`_.
- **Note:** Due to the constraints of the default database schema, the SQL
- handler limits the length of the ``$ident`` string to sixteen (16) characters.
- This limit can be adjusted using the ``identLimit`` configuration parameter.
- The Log Table
- ~~~~~~~~~~~~~
- The default SQL table used by this handler looks like this::
- CREATE TABLE log_table (
- id INT NOT NULL,
- logtime TIMESTAMP NOT NULL,
- ident CHAR(16) NOT NULL,
- priority INT NOT NULL,
- message VARCHAR(200),
- PRIMARY KEY (id)
- );
- This is the "lowest common denominator" that should work across all SQL
- compliant database. You may want to make database- or site-specific changes
- to this schema to support your specific needs, however. For example,
- `PostgreSQL`_ users may prefer to use a ``TEXT`` type for the ``message``
- field.
- .. _PostgreSQL: http://www.postgresql.org/
- Configuration
- ~~~~~~~~~~~~~
- +-------------------+-----------+---------------+---------------------------+
- | Parameter | Type | Default | Description |
- +===================+===========+===============+===========================+
- | ``dsn`` | Mixed | '' `(empty)` | A `Data Source Name`_. |
- | | | | |required| |
- +-------------------+-----------+---------------+---------------------------+
- | ``sql`` | String | |sql-default| | SQL insertion statement. |
- +-------------------+-----------+---------------+---------------------------+
- | ``options`` | Array | ``persistent``| An array of `DB`_ options.|
- +-------------------+-----------+---------------+---------------------------+
- | ``db`` | Object | NULL | An existing `DB`_ object. |
- | | | | If specified, this object |
- | | | | will be used, and ``dsn`` |
- | | | | will be ignored. |
- +-------------------+-----------+---------------+---------------------------+
- | ``sequence`` | String | ``log_id`` | The name of the sequence |
- | | | | to use when generating |
- | | | | unique event IDs. Under |
- | | | | many databases, this will |
- | | | | be used as the name of |
- | | | | the sequence table. |
- +-------------------+-----------+---------------+---------------------------+
- | ``identLimit`` | Integer | 16 | The maximum length of the |
- | | | | ``ident`` string. |
- | | | | **Changing this value may |
- | | | | require updates to the SQL|
- | | | | schema, as well.** |
- +-------------------+-----------+---------------+---------------------------+
- The name of the database table to which the log entries will be written is
- specified using the ``$name`` construction parameter (see `Configuring a
- Handler`_).
- .. |sql-default| replace:: ``INSERT INTO $table (id, logtime, ident, priority, message) VALUES(?, CURRENT_TIMESTAMP, ?, ?, ?)``
- .. _DB: http://pear.php.net/package/DB
- .. _PEAR's DB abstraction layer: DB_
- .. _Data Source Name: http://pear.php.net/manual/en/package.database.db.intro-dsn.php
- Examples
- ~~~~~~~~
- Using a `Data Source Name`_ to create a new database connection::
- $conf = array('dsn' => 'pgsql://jon@localhost+unix/logs');
- $logger = &Log::singleton('sql', 'log_table', 'ident', $conf);
- for ($i = 0; $i < 10; $i++) {
- $logger->log("Log entry $i");
- }
- Using an existing `DB`_ object::
- require_once 'DB.php';
- $db = &DB::connect('pgsql://jon@localhost+unix/logs');
- $conf['db'] = $db;
- $logger = &Log::singleton('sql', 'log_table', 'ident', $conf);
- for ($i = 0; $i < 10; $i++) {
- $logger->log("Log entry $i");
- }
- The Sqlite Handler
- ------------------
- :Author: Bertrand Mansion
- The Sqlite handler sends log events to an Sqlite database using the `native
- PHP sqlite functions`_.
- It is faster than `the SQL (DB) handler`_ because requests are made directly
- to the database without using an abstraction layer. It is also interesting to
- note that Sqlite database files can be moved, copied, and deleted on your
- system just like any other files, which makes log management easier. Last but
- not least, using a database to log your events allows you to use SQL queries
- to create reports and statistics.
- When using a database and logging a lot of events, it is recommended to split
- the database into smaller databases. This is allowed by Sqlite, and you can
- later use the Sqlite `ATTACH`_ statement to query your log database files
- globally.
- If the database does not exist when the log is opened, sqlite will try to
- create it automatically. If the log table does not exist, it will also be
- automatically created. The table creation uses the following SQL request::
- CREATE TABLE log_table (
- id INTEGER PRIMARY KEY NOT NULL,
- logtime NOT NULL,
- ident CHAR(16) NOT NULL,
- priority INT NOT NULL,
- message
- );
- 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.
- Configuration
- ~~~~~~~~~~~~~
- +-------------------+-----------+---------------+---------------------------+
- | Parameter | Type | Default | Description |
- +===================+===========+===============+===========================+
- | ``inherit`` | Boolean | false | Inherit the current syslog|
- | | | | connection for this |
- | | | | process, or start a new |
- | | | | one via `openlog()`_? |
- +-------------------+-----------+---------------+---------------------------+
- 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
- .. _openlog(): http://www.php.net/openlog
- 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. |
- +-------------------+-----------+---------------+---------------------------+
- | ``styles`` | Array | `ROY G BIV`_ | Mapping of log priorities |
- | | | (high to low) | to CSS styles. |
- +-------------------+-----------+---------------+---------------------------+
- **Note:** The Window handler may not work reliably when PHP's `output
- buffering`_ system is enabled.
- .. _"JavaScript Power PHP Debugging": http://www.zend.com/zend/tut/tutorial-DebugLib.php
- .. _ROY G BIV: http://www.cis.rit.edu/
- .. _output buffering: http://www.php.net/outcontrol
- 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://wikipedia.org/wiki/Observer_pattern
- 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:
- $priority = 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 PHP Assertions
- ----------------------
- PHP allows user-defined `assert()`_ callback handlers. The assertion callback
- is configured using the `assert_options()`_ function.
- ::
- function assertCallback($file, $line, $message)
- {
- global $logger;
- $logger->log($message . ' in ' . $file . ' at line ' . $line,
- PEAR_LOG_ALERT);
- }
- assert_options(ASSERT_CALLBACK, 'assertCallback');
- assert(false);
- .. _assert(): http://www.php.net/assert
- .. _assert_options(): http://www.php.net/assert_options
- Logging PHP Exceptions
- ----------------------
- PHP 5 and later support the concept of `exceptions`_. A custom exception
- handler can be assigned using the `set_exception_handler()`_ function.
- ::
- function exceptionHandler($exception)
- {
- global $logger;
- $logger->log($exception->getMessage(), PEAR_LOG_ALERT);
- }
- set_exception_handler('exceptionHandler');
- throw new Exception('Uncaught Exception');
- .. _exceptions: http://www.php.net/exceptions
- .. _set_exception_handler(): http://www.php.net/set_exception_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
- --------------------
- Writing a new …
Large files files are truncated, but you can click here to view the full file