Log
[ class tree: Log ] [ index: Log ] [ all elements ]

Class: Log

Source Location: /Log-1.12.8/Log.php

Class Overview


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


Author(s):

Variables

Methods


Child classes:

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).
Log_mail
The Log_mail class is a concrete implementation of the Log:: abstract class which sends log messages to a mailbox.
Log_mdb2
The Log_mdb2 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.
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.
Log_file
The Log_file class is a concrete implementation of the Log abstract class that logs messages to a text file.
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.
Log_daemon
The Log_daemon class is a concrete implementation of the Log:: abstract class which sends messages to syslog daemon on UNIX-like machines.
Log_display
The Log_display class is a concrete implementation of the Log:: abstract class which writes message into browser in usual PHP maner.
Log_composite
The Log_composite:: class implements a Composite pattern which allows multiple Log implementations to receive the same events.
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.
Log_console
The Log_console class is a concrete implementation of the Log:: abstract class which writes message to the text console.
Log_sqlite
The Log_sqlite class is a concrete implementation of the Log:: abstract class which sends messages to an Sqlite database.
Log_firebug
The Log_firebug class is a concrete implementation of the Log:: abstract class which writes message into Firebug console.
Log_win
The Log_win class is a concrete implementation of the Log abstract class that logs messages to a separate browser window.
Log_null
The Log_null class is a concrete implementation of the Log:: abstract class. It simply consumes log events.

Inherited Variables

Inherited Methods


Class Details

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


[ Top ]


Class Variables

$_backtrace_depth =  0

[line 95]

Starting depth to use when walking a backtrace in search of the function that invoked the log system.
  • Access: protected

Type:   integer


[ Top ]

$_formatMap = array('%{timestamp}'  => '%1$s',
                            '%{ident}'      => '%2$s',
                            '%{priority}'   => '%3$s',
                            '%{message}'    => '%4$s',
                            '%{file}'       => '%5$s',
                            '%{line}'       => '%6$s',
                            '%{function}'   => '%7$s',
                            '%{class}'      => '%8$s',
                            '%\{'           => '%%{')

[line 104]

Maps canonical format keys to position arguments for use in building "line format" strings.
  • Access: protected

Type:   array


[ Top ]

$_id =  0

[line 54]

Instance-specific unique identification number.
  • Access: protected

Type:   integer


[ Top ]

$_ident =  ''

[line 62]

The label that uniquely identifies this set of log messages.
  • Access: protected

Type:   string


[ Top ]

$_listeners = array()

[line 86]

Holds all Log_observer objects that wish to be notified of new messages.
  • Access: protected

Type:   array


[ Top ]

$_mask =  PEAR_LOG_ALL

[line 78]

The bitmask of allowed log levels.
  • Access: protected

Type:   integer


[ Top ]

$_opened =  false

[line 46]

Indicates whether or not the log can been opened / connected.
  • Access: protected

Type:   boolean


[ Top ]

$_priority =  PEAR_LOG_INFO

[line 70]

The default priority to use when logging an event.
  • Access: protected

Type:   integer


[ Top ]



Method Detail

alert   [line 281]

boolean alert( mixed $message)

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

Parameters:

mixed   $message     String or object containing the message to log.

[ Top ]

attach   [line 779]

boolean attach( &$observer, object $observer)

Adds a Log_observer instance to the list of observers that are listening for messages emitted by this Log instance.
  • Return: True if the observer is successfully attached.
  • Since: Log 1.0
  • Access: public

Parameters:

object   $observer     The Log_observer instance to attach as a listener.
   &$observer     

[ Top ]

close   [line 229]

void close( )

Abstract implementation of the close() method.
  • Since: Log 1.0

Overridden in child classes as:

Log_syslog::close()
Closes the connection to the system logger, if it is open.
Log_mail::close()
Closes the message, if it is open, and sends the mail.
Log_mdb2::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_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_file::close()
Closes the log file if it is open.
Log_error_log::close()
Closes the handler.
Log_daemon::close()
Closes the connection to the system logger, if it is open.
Log_display::close()
Closes the display handler.
Log_composite::close()
Closes all open child instances.
Log_mcal::close()
Closes the calendar stream, if it is open.
Log_console::close()
Closes the output stream.
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'].
Log_firebug::close()
Closes the firebug handler.
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_null::close()
Closes the handler.

[ Top ]

crit   [line 298]

boolean crit( mixed $message)

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

Parameters:

mixed   $message     String or object containing the message to log.

[ Top ]

debug   [line 383]

boolean debug( mixed $message)

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

Parameters:

mixed   $message     String or object containing the message to log.

[ Top ]

detach   [line 801]

boolean detach( object $observer)

Removes a Log_observer instance from the list of observers.
  • Return: True if the observer is successfully detached.
  • Since: Log 1.0
  • Access: public

Parameters:

object   $observer     The Log_observer instance to detach from the list of listeners.

[ Top ]

emerg   [line 264]

boolean emerg( mixed $message)

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

Parameters:

mixed   $message     String or object containing the message to log.

[ Top ]

err   [line 315]

boolean err( mixed $message)

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

Parameters:

mixed   $message     String or object containing the message to log.

[ Top ]

factory   [line 139]

object Log factory( string $handler, [string $name = ''], [string $ident = ''], [array $conf = array()], [int $level = PEAR_LOG_DEBUG])

Attempts to return a concrete Log instance of type $handler.
  • Return: The newly created concrete Log instance, or null on an error.
  • Since: Log 1.0
  • Access: public

Parameters:

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.

[ Top ]

flush   [line 238]

void flush( )

Abstract implementation of the flush() method.
  • Since: Log 1.8.2

Overridden in child classes as:

Log_mail::flush()
Flushes the log output by forcing the email message to be sent now.
Log_file::flush()
Flushes all pending data to the file handle.
Log_composite::flush()
Flushes all child instances. It is assumed that all of the children have been successfully opened.
Log_console::flush()
Flushes all pending ("buffered") data to the output stream.
Log_firebug::flush()
Flushes all pending ("buffered") data.

[ Top ]

getIdent   [line 864]

string getIdent( )

Returns the current identification string.
  • Return: The current Log instance's identification string.
  • Since: Log 1.6.3
  • Access: public

[ Top ]

getMask   [line 720]

interger getMask( )

Returns the current level mask.
  • Return: The current level mask.
  • Since: Log 1.7.0
  • Access: public

[ Top ]

getPriority   [line 749]

integer getPriority( )

Returns the current default priority.
  • Return: The current default priority.
  • Since: Log 1.8.4
  • Access: public

[ Top ]

info   [line 366]

boolean info( mixed $message)

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

Parameters:

mixed   $message     String or object containing the message to log.

[ Top ]

isComposite   [line 838]

boolean isComposite( )

Indicates whether this is a composite class.
  • Return: True if this is a composite class.
  • Since: Log 1.0
  • Access: public

Overridden in child classes as:

Log_composite::isComposite()
Returns true if this is a composite.

[ Top ]

log   [line 247]

void log( $message, [ $priority = null])

Abstract implementation of the log() method.
  • Since: Log 1.0

Overridden in child classes as:

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_mail::log()
Writes $message to the currently open mail message.
Log_mdb2::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_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_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_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_daemon::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_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. If the appropriate children aren't already open, they will be opened here.
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_console::log()
Writes $message to the text console. 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.
Log_firebug::log()
Writes $message to Firebug 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_null::log()
Simply consumes the log event. The message will still be passed along to any Log_observer instances that are observing this Log.

Parameters:

   $message     
   $priority     

[ Top ]

MASK   [line 633]

integer MASK( integer $priority)

Calculate the log mask for the given priority.

This method may be called statically.

  • Return: The calculated log mask.
  • Since: Log 1.7.0
  • Access: public

Parameters:

integer   $priority     The priority whose mask will be calculated.

[ Top ]

MAX   [line 690]

integer MAX( integer $priority)

Calculate the log mask for all priorities less than or equal to the given priority. In other words, $priority will be the highests priority matched by the resulting mask.

This method may be called statically.

  • Return: The resulting log mask.
  • Since: Log 1.9.4
  • Access: public

Parameters:

integer   $priority     The maximum priority covered by this mask.

[ Top ]

MIN   [line 671]

integer MIN( integer $priority)

Calculate the log mask for all priorities greater than or equal to the given priority. In other words, $priority will be the lowest priority matched by the resulting mask.

This method may be called statically.

  • Return: The resulting log mask.
  • Since: Log 1.9.4
  • Access: public

Parameters:

integer   $priority     The minimum priority covered by this mask.

[ Top ]

notice   [line 349]

boolean notice( mixed $message)

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

Parameters:

mixed   $message     String or object containing the message to log.

[ Top ]

open   [line 220]

void open( )

Abstract implementation of the open() method.
  • Since: Log 1.0

Overridden in child classes as:

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_mail::open()
Starts a new mail message.
Log_mdb2::open()
Opens a connection to the database, if it has not already been opened. This is implicitly called by log(), if necessary.
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_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_error_log::open()
Opens the handler.
Log_daemon::open()
Opens a connection to the system logger, if it has not already been opened. This is implicitly called by log(), if necessary.
Log_display::open()
Opens the display handler.
Log_composite::open()
Opens all of the child instances.
Log_mcal::open()
Opens a calendar stream, if it has not already been opened. This is implicitly called by log(), if necessary.
Log_console::open()
Open the output stream.
Log_sqlite::open()
Opens a connection to the database, if it has not already been opened. This is implicitly called by log(), if necessary.
Log_firebug::open()
Opens the firebug handler.
Log_win::open()
The first time open() is called, it will open a new browser window and prepare it for output.
Log_null::open()
Opens the handler.

[ Top ]

priorityToString   [line 576]

string priorityToString( int $priority)

Returns the string representation of a PEAR_LOG_* integer constant.
  • Return: The string representation of $level.
  • Since: Log 1.0
  • Access: public

Parameters:

int   $priority     A PEAR_LOG_* integer constant.

[ Top ]

setBacktraceDepth   [line 524]

void setBacktraceDepth( int $depth)

Sets the starting depth to use when walking a backtrace in search of the function that invoked the log system. This is used on conjunction with the 'file', 'line', 'function', and 'class' formatters.
  • Since: Log 1.12.7
  • Access: public

Parameters:

int   $depth     The new backtrace depth.

[ Top ]

setIdent   [line 851]

void setIdent( string $ident)

Sets this Log instance's identification string.
  • Since: Log 1.6.3
  • Access: public

Overridden in child classes as:

Log_mdb2::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.
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.
Log_composite::setIdent()
Sets this identification string for all of this composite's children.

Parameters:

string   $ident     The new identification string.

[ Top ]

setMask   [line 705]

integer setMask( integer $mask)

Set and return the level mask for the current Log instance.
  • Return: The current level mask.
  • Since: Log 1.7.0
  • Access: public

Parameters:

integer   $mask     A bitwise mask of log levels.

[ Top ]

setPriority   [line 762]

void setPriority( integer $priority)

Sets the default priority to the specified value.
  • Since: Log 1.8.4
  • Access: public

Parameters:

integer   $priority     The new default priority.

[ Top ]

singleton   [line 201]

object Log singleton( string $handler, [string $name = ''], [string $ident = ''], [array $conf = array()], [int $level = PEAR_LOG_DEBUG])

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 null on an error.
  • Since: Log 1.0
  • Access: public

Parameters:

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.

[ Top ]

stringToPriority   [line 605]

string stringToPriority( string $name)

Returns the the PEAR_LOG_* integer constant for the given string representation of a priority name. This function performs a case-insensitive search.
  • Return: The PEAR_LOG_* integer contstant corresponding the the specified priority name.
  • Since: Log 1.9.0
  • Access: public

Parameters:

string   $name     String containing a priority name.

[ Top ]

UPTO   [line 652]

integer UPTO( integer $priority)

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

This method may be called statically.

  • Return: The resulting log mask.
  • Deprecated: deprecated since Log 1.9.4; use Log::MAX() instead
  • Since: Log 1.7.0
  • Access: public

Parameters:

integer   $priority     The maximum priority covered by this mask.

[ Top ]

warning   [line 332]

boolean warning( mixed $message)

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

Parameters:

mixed   $message     String or object containing the message to log.

[ Top ]

_announce   [line 821]

void _announce( array $event)

Informs each registered observer instance that a new message has been logged.
  • Access: protected

Parameters:

array   $event     A hash describing the log event.

[ Top ]

_extractMessage   [line 405]

string _extractMessage( mixed $message)

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: protected

Parameters:

mixed   $message     The original message data. This may be a string or any object.

[ Top ]

_format   [line 538]

string _format( $format, $timestamp, $priority, $message)

Produces a formatted log line based on a format string and a set of variables representing the current log record and state.
  • Return: Formatted log string.
  • Since: Log 1.9.4
  • Access: protected

Parameters:

   $format     
   $timestamp     
   $priority     
   $message     

[ Top ]

_isMasked   [line 736]

boolean _isMasked( integer $priority)

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: protected

Parameters:

integer   $priority     The priority to check.

[ Top ]


Documentation generated on Sat, 12 Jul 2014 20:30:06 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.