Class Log

Description

The Log:: class implements both an abstraction for various logging mechanisms and the Subject end of a Subject-Observer pattern.

Located in /maintenance/libraries/pear/Log.php (line 37)


	
			
Direct descendents
Class Description
 class Log_null The Log_null class is a concrete implementation of the Log:: abstract class. It simply consumes log events.
 class Log_error_log The Log_error_log class is a concrete implementation of the Log abstract class that logs messages using PHP's error_log() function.
 class Log_display The Log_display class is a concrete implementation of the Log:: abstract class which writes message into browser in usual PHP maner.
 class Log_composite The Log_composite:: class implements a Composite pattern which allows multiple Log implementations to receive the same events.
 class Log_sql The Log_sql class is a concrete implementation of the Log:: abstract class which sends messages to an SQL server. Each entry occupies a separate row in the database.
 class Log_console The Log_console class is a concrete implementation of the Log:: abstract class which writes message to the text console.
 class Log_win The Log_win class is a concrete implementation of the Log abstract class that logs messages to a separate browser window.
 class Log_file The Log_file class is a concrete implementation of the Log abstract class that logs messages to a text file.
 class Log_mail The Log_mail class is a concrete implementation of the Log:: abstract class which sends log messages to a mailbox.
 class Log_syslog The Log_syslog class is a concrete implementation of the Log:: abstract class which sends messages to syslog on UNIX-like machines (PHP emulates this with the Event Log on Windows machines).
 class Log_mcal The Log_mcal class is a concrete implementation of the Log:: abstract class which sends messages to a local or remote calendar store accessed through MCAL.
 class Log_sqlite The Log_sqlite class is a concrete implementation of the Log:: abstract class which sends messages to an Sqlite database.
Variable Summary
 integer $_id
 string $_ident
 array $_listeners
 integer $_mask
 boolean $_opened
 integer $_priority
Method Summary
 boolean alert (mixed $message)
 void attach (object &$observer, boolean 1)
 void close ()
 boolean crit (mixed $message)
 boolean debug (mixed $message)
 void detach (object $observer, boolean 1)
 boolean emerg (mixed $message)
 boolean err (mixed $message)
 object Log &factory (string $handler, [string $name = ''], [string $ident = ''], [array $conf = array()], [int $level = PEAR_LOG_DEBUG])
 void flush ()
 string getIdent ()
 interger getMask ()
 integer getPriority ()
 boolean info (mixed $message)
 boolean isComposite ()
 void log (mixed $message, [mixed $priority = null])
 integer MASK (integer $priority)
 boolean notice (mixed $message)
 void open ()
 string priorityToString (int $priority)
 void setIdent (string $ident)
 integer setMask (integer $mask)
 void setPriority (integer $priority)
 object Log &singleton (string $handler, [string $name = ''], [string $ident = ''], [array $conf = array()], [int $level = PEAR_LOG_DEBUG])
 integer UPTO (integer $priority)
 boolean warning (mixed $message)
 void _announce (array $event)
 string _extractMessage (mixed $message)
 boolean _isMasked (integer $priority)
Variables
integer $_id = 0 (line 53)

Instance-specific unique identification number.

  • access: private
string $_ident = '' (line 61)

The label that uniquely identifies this set of log messages.

  • access: private
array $_listeners = array() (line 84)

Holds all Log_observer objects that wish to be notified of new messages.

  • access: private
integer $_mask = PEAR_LOG_ALL (line 76)

The bitmask of allowed log levels.

  • access: private
boolean $_opened = false (line 45)

Indicates whether or not the log can been opened / connected.

  • access: private
integer $_priority = PEAR_LOG_INFO (line 69)

The default priority to use when logging an event.

  • access: private
Methods
alert (line 250)

A convenience function for logging an alert event. It will log a message at the PEAR_LOG_ALERT log level.

  • return: True if the message was successfully logged.
  • since: Log 1.7.0
  • access: public
boolean alert (mixed $message)
  • mixed $message: String or object containing the message to log.
attach (line 540)

Adds a Log_observer instance to the list of observers that are listening for messages emitted by this Log instance.

  • since: Log 1.0
  • access: public
void attach (object &$observer, boolean 1)
  • object $observer: The Log_observer instance to attach as a listener.
  • boolean 1: True if the observer is successfully attached.
close (line 198)

Abstract implementation of the close() method.

  • since: Log 1.0
void close ()

Redefined in descendants as:
  • Log_composite::close() : Closes any child instances.
  • Log_sql::close() : Closes the connection to the database if it is still open and we were the ones that opened it. It is the caller's responsible to close an existing connection that was passed to us via $conf['db'].
  • Log_win::close() : Closes the output stream if it is open. If there are still pending lines in the output buffer, the output window will be opened so that the buffer can be drained.
  • Log_file::close() : Closes the log file if it is open.
  • Log_mail::close() : Closes the message, if it is open, and sends the mail.
  • Log_syslog::close() : Closes the connection to the system logger, if it is open.
  • Log_mcal::close() : Closes the calendar stream, if it is open.
  • Log_sqlite::close() : Closes the connection to the database if it is still open and we were the ones that opened it. It is the caller's responsible to close an existing connection that was passed to us via $conf['db'].
crit (line 267)

A convenience function for logging a critical event. It will log a message at the PEAR_LOG_CRIT log level.

  • return: True if the message was successfully logged.
  • since: Log 1.7.0
  • access: public
boolean crit (mixed $message)
  • mixed $message: String or object containing the message to log.
debug (line 352)

A convenience function for logging a debug event. It will log a message at the PEAR_LOG_DEBUG log level.

  • return: True if the message was successfully logged.
  • since: Log 1.7.0
  • access: public
boolean debug (mixed $message)
  • mixed $message: String or object containing the message to log.
detach (line 562)

Removes a Log_observer instance from the list of observers.

  • since: Log 1.0
  • access: public
void detach (object $observer, boolean 1)
  • object $observer: The Log_observer instance to detach from the list of listeners.
  • boolean 1: True if the observer is successfully detached.
emerg (line 233)

A convenience function for logging a emergency event. It will log a message at the PEAR_LOG_EMERG log level.

  • return: True if the message was successfully logged.
  • since: Log 1.7.0
  • access: public
boolean emerg (mixed $message)
  • mixed $message: String or object containing the message to log.
err (line 284)

A convenience function for logging a error event. It will log a message at the PEAR_LOG_ERR log level.

  • return: True if the message was successfully logged.
  • since: Log 1.7.0
  • access: public
boolean err (mixed $message)
  • mixed $message: String or object containing the message to log.
factory (line 112)

Attempts to return a concrete Log instance of type $handler.

  • return: The newly created concrete Log instance, or an false on an error.
  • since: Log 1.0
  • access: public
object Log &factory (string $handler, [string $name = ''], [string $ident = ''], [array $conf = array()], [int $level = PEAR_LOG_DEBUG])
  • string $handler: The type of concrete Log subclass to return. Attempt to dynamically include the code for this subclass. Currently, valid values are 'console', 'syslog', 'sql', 'file', and 'mcal'.
  • string $name: The name of the actually log file, table, or other specific store to use. Defaults to an empty string, with which the subclass will attempt to do something intelligent.
  • string $ident: The identity reported to the log system.
  • array $conf: A hash containing any additional configuration information that a subclass might need.
  • int $level: Log messages up to and including this level.
flush (line 207)

Abstract implementation of the flush() method.

  • since: Log 1.8.2
void flush ()

Redefined in descendants as:
getIdent (line 625)

Returns the current identification string.

  • return: The current Log instance's identification string.
  • since: Log 1.6.3
  • access: public
string getIdent ()
getMask (line 481)

Returns the current level mask.

  • return: The current level mask.
  • since: Log 1.7.0
  • access: public
interger getMask ()
getPriority (line 510)

Returns the current default priority.

  • return: The current default priority.
  • since: Log 1.8.4
  • access: public
integer getPriority ()
info (line 335)

A convenience function for logging a information event. It will log a message at the PEAR_LOG_INFO log level.

  • return: True if the message was successfully logged.
  • since: Log 1.7.0
  • access: public
boolean info (mixed $message)
  • mixed $message: String or object containing the message to log.
isComposite (line 599)

Indicates whether this is a composite class.

  • return: True if this is a composite class.
  • since: Log 1.0
  • access: public
boolean isComposite ()

Redefined in descendants as:
log (line 216)

Abstract implementation of the log() method.

  • since: Log 1.0
void log (mixed $message, [mixed $priority = null])

Redefined in descendants as:
  • Log_null::log() : Simply consumes the log event. The message will still be passed along to any Log_observer instances that are observing this Log.
  • Log_error_log::log() : Logs $message using PHP's error_log() function. The message is also passed along to any Log_observer instances that are observing this Log.
  • Log_display::log() : Writes $message to the text browser. Also, passes the message along to any Log_observer instances that are observing this Log.
  • Log_composite::log() : Sends $message and $priority to each child of this composite.
  • Log_sql::log() : Inserts $message to the currently open database. Calls open(), if necessary. Also passes the message along to any Log_observer instances that are observing this Log.
  • Log_console::log() : Writes $message to the text console. Also, passes the message along to any Log_observer instances that are observing this Log.
  • Log_win::log() : Logs $message to the output window. The message is also passed along to any Log_observer instances that are observing this Log.
  • Log_file::log() : Logs $message to the output window. The message is also passed along to any Log_observer instances that are observing this Log.
  • Log_mail::log() : Writes $message to the currently open mail message.
  • Log_syslog::log() : Sends $message to the currently open syslog connection. Calls open() if necessary. Also passes the message along to any Log_observer instances that are observing this Log.
  • Log_mcal::log() : Logs $message and associated information to the currently open calendar stream. Calls open() if necessary. Also passes the message along to any Log_observer instances that are observing this Log.
  • Log_sqlite::log() : Inserts $message to the currently open database. Calls open(), if necessary. Also passes the message along to any Log_observer instances that are observing this Log.
MASK (line 436)

Calculate the log mask for the given priority.

  • return: The calculated log mask.
  • since: Log 1.7.0
  • access: public
integer MASK (integer $priority)
  • integer $priority: The priority whose mask will be calculated.
notice (line 318)

A convenience function for logging a notice event. It will log a message at the PEAR_LOG_NOTICE log level.

  • return: True if the message was successfully logged.
  • since: Log 1.7.0
  • access: public
boolean notice (mixed $message)
  • mixed $message: String or object containing the message to log.
open (line 189)

Abstract implementation of the open() method.

  • since: Log 1.0
void open ()

Redefined in descendants as:
  • Log_composite::open() : Opens the child connections.
  • Log_sql::open() : Opens a connection to the database, if it has not already been opened. This is implicitly called by log(), if necessary.
  • Log_win::open() : The first time open() is called, it will open a new browser window and prepare it for output.
  • Log_file::open() : Opens the log file for output. If the specified log file does not already exist, it will be created. By default, new log entries are appended to the end of the log file.
  • Log_mail::open() : Starts a new mail message.
  • Log_syslog::open() : Opens a connection to the system logger, if it has not already been opened. This is implicitly called by log(), if necessary.
  • Log_mcal::open() : Opens a calendar stream, if it has not already been opened. This is implicitly called by log(), if necessary.
  • Log_sqlite::open() : Opens a connection to the database, if it has not already been opened. This is implicitly called by log(), if necessary.
priorityToString (line 410)

Returns the string representation of a PEAR_LOG_* integer constant.

  • return: The string representation of $level.
  • since: Log 1.0
string priorityToString (int $priority)
  • int $priority: A PEAR_LOG_* integer constant.
setIdent (line 612)

Sets this Log instance's identification string.

  • since: Log 1.6.3
  • access: public
void setIdent (string $ident)
  • string $ident: The new identification string.

Redefined in descendants as:
  • Log_composite::setIdent() : Sets this identification string for all of this composite's children.
  • Log_sql::setIdent() : Sets this Log instance's identification string. Note that this SQL-specific implementation will limit the length of the $ident string to sixteen (16) characters.
setMask (line 466)

Set and return the level mask for the current Log instance.

  • return: The current level mask.
  • since: Log 1.7.0
  • access: public
integer setMask (integer $mask)
  • integer $mask: A bitwise mask of log levels.
setPriority (line 523)

Sets the default priority to the specified value.

  • since: Log 1.8.4
  • access: public
void setPriority (integer $priority)
  • integer $priority: The new default priority.
singleton (line 170)

Attempts to return a reference to a concrete Log instance of type $handler, only creating a new instance if no log instance with the same parameters currently exists.

You should use this if there are multiple places you might create a logger, you don't want to create multiple loggers, and you don't want to check for the existance of one each time. The singleton pattern does all the checking work for you.

You MUST call this method with the $var = &Log::singleton() syntax. Without the ampersand (&) in front of the method name, you will not get a reference, you will get a copy.

  • return: The newly created concrete Log instance, or an false on an error.
  • since: Log 1.0
  • access: public
object Log &singleton (string $handler, [string $name = ''], [string $ident = ''], [array $conf = array()], [int $level = PEAR_LOG_DEBUG])
  • string $handler: The type of concrete Log subclass to return. Attempt to dynamically include the code for this subclass. Currently, valid values are 'console', 'syslog', 'sql', 'file', and 'mcal'.
  • string $name: The name of the actually log file, table, or other specific store to use. Defaults to an empty string, with which the subclass will attempt to do something intelligent.
  • string $ident: The identity reported to the log system.
  • array $conf: A hash containing any additional configuration information that a subclass might need.
  • int $level: Log messages up to and including this level.
UPTO (line 451)

Calculate the log mask for all priorities up to the given priority.

  • return: The calculated log mask.
  • since: Log 1.7.0
  • access: public
integer UPTO (integer $priority)
  • integer $priority: The maximum priority covered by this mask.
warning (line 301)

A convenience function for logging a warning event. It will log a message at the PEAR_LOG_WARNING log level.

  • return: True if the message was successfully logged.
  • since: Log 1.7.0
  • access: public
boolean warning (mixed $message)
  • mixed $message: String or object containing the message to log.
_announce (line 582)

Informs each registered observer instance that a new message has been logged.

  • access: private
void _announce (array $event)
  • array $event: A hash describing the log event.
_extractMessage (line 374)

Returns the string representation of the message data.

If $message is an object, _extractMessage() will attempt to extract the message text using a known method (such as a PEAR_Error object's getMessage() method). If a known method, cannot be found, the serialized representation of the object will be returned.

If the message data is already a string, it will be returned unchanged.

  • return: The string representation of the message.
  • access: private
string _extractMessage (mixed $message)
  • mixed $message: The original message data. This may be a string or any object.
_isMasked (line 497)

Check if the given priority is included in the current level mask.

  • return: True if the given priority is included in the current log mask.
  • since: Log 1.7.0
  • access: private
boolean _isMasked (integer $priority)
  • integer $priority: The priority to check.

Documentation generated on Fri, 11 Feb 2005 18:13:30 +0000 by phpDocumentor 1.3.0RC3