spunQ_Logger Class Reference

spunQ logging facility. More...

List of all members.

Public Member Functions

vdebug ($message)

Log a message with debug-level priority.

debug ($message)

Log a message with debug-level priority.

info ($message)

Log a message with info-level priority.

warning ($message)

Log a message with warning-level priority.

error ($message)

Log a message with error-level priority.

critical ($message)

Log a message with error-level priority.

logMessage ($priority, $message)

Log a message with arbitrary priority.

addRule (spunQ_LoggerRule $rule)

Adds a rule to the logger.

removeRule (spunQ_LoggerRule $rule)

Removes a rule from the logger.

clearAllRules ()

Removes all previously defined rules.

Static Public Member Functions

static getInstance ()

Retrieves Singleton instance.

Public Attributes

const VERBOSE_DEBUG = 0

The lowest possible log-level.

const VDEBUG = 0

Alias for VERBOSE_DEBUG.

const DEBUG = 10

Informative level for developers.

const INFO = 20

Informative level for users.

const WARNING = 30

Level for recoverable errors.

const ERROR = 40

Level for unrecoverable errors.

const CRITICAL = 50

Level for errors that require immediate attention.

const MAX_STACK_SIZE = 10

Maximum number of log messages that shall be in queue.

Protected Member Functions

__construct ()

Constructor.

Protected Attributes

$messageStack = 0

Amount of messages that are in queue to be logged.

Private Member Functions

fileToPath ($file, $function=NULL)

Constructs a path definition out of a file-system path.

formatFileToPath ($folder, $file)

Formats the file between the folder and the file in spunQ's format.

setLowestPriority ()

Sets the class variable lowestPriorityRule.

getCaller ()

Uses spunQ_Backtrace to find calling function.

getLoggingRules ($path, $priority)

Finds the matching rule for the given caller and the given priority.

Private Attributes

$rules = array()

Rules that have been defined.

$lowestPriorityRule = 100

Required for speed optimization.

Static Private Attributes

static $instance = NULL

Singleton instance.

Detailed Description

spunQ logging facility.

To be able to log messages, the logger needs to know what to log and how to log it. The logger provides the possibility of defining rules that describe the condition to log and of having a LogTarget, which will take care of the actual logging. Rules can be added and removed. A rule consists of three components: A path, a level and a LogTarget.

Path: The term path describes the source of a logging event. This source is defined by the source file and line the event was triggered. For simplicity, it makes use of the module aliases in spunQ. This file, for example, is in the spunQ folder in core/logger/Logger.class.php. The corresponding path would be 'spunQ.logger.Logger'. Note that the extensions of the file are dropped for readability.
The function where the event to be logged originated is also added to the path. Thus if the event were triggered in a function called myfunction(), then the corresponding path would be 'spunQ.logger.Logger.myfunction()'. A path definition for the establishment of logger rules consists of a string that must match the first part of the log event's path. The asterisk may be used as a wildcard for matching arbitrary-length strings. Some path definitions that would match this file's path:
- spunQ
- spunQ
- spunQ* (Essentially the same as above)
- spunQ.logger.Logger
- spunQ.logger.Logger.myfunction()
- spunQ.logger.Logger.??function()
- spunQ.logger.Logger*
- spunQ.*.Logger
- *Logger
Level: Log events can have several levels, reaching from verbose debug to critical. Although this is actually a numeric value, it is good practice to stick to the log level constants defined in this class. A rule will match any log event with equal or higher priority, which means That a rule for VDEBUG events will match any level (since VDEBUG has the least priority).
LogTarget: The spunQ_ILogTarget that will receive the logging event for further processing, if the path and the priority of a triggered log event match the rule.

Event sources with their file extensions can be registered and used to determine the path source displayed by the logger. A DefaultEventSource can also be configured in test.spunQ.conf. If neither of these paths match, the Logger will show the entire path. The paths are display in the dotted format shown above, preceded by a name dependent on the file type and the events and extensions registered, followed by a colon. For more information see the devlog and the PHPUnit tests.

Definition at line 169 of file Logger.class.php.

Member Function Documentation

spunQ_Logger::addRule ( spunQ_LoggerRule $ rule )

Adds a rule to the logger.

The rule consists of a path, a priority and a logTarget. The logTarget is used for logging events in the specified path with at least the specified priority.

Parameters:

$rule

The rule to be added

See also:: spunQ_Logger
spunQ_LoggerRule

Returns:: spunQ_LoggerRule The rule that was added

Definition at line 389 of file Logger.class.php.

spunQ_Logger::clearAllRules ( )

Removes all previously defined rules.

Mainly required for testing.

Returns:: void

Definition at line 481 of file Logger.class.php.

spunQ_Logger::critical ( $ message )

Log a message with error-level priority.

Parameters:

$message

An arbitrary message - could be an object, too

Returns:: void (logMessage returns void)

Definition at line 312 of file Logger.class.php.

spunQ_Logger::debug ( $ message )

Log a message with debug-level priority.

Parameters:

$message

An arbitrary message - could be an object, too

Returns:: void (logMessage returns void)

Definition at line 276 of file Logger.class.php.

spunQ_Logger::error ( $ message )

Log a message with error-level priority.

Parameters:

$message

An arbitrary message - could be an object, too

Returns:: void (logMessage returns void)

Definition at line 303 of file Logger.class.php.

spunQ_Logger::fileToPath	(	$	file,
		$	function = `NULL`
	)			`[private]`

Constructs a path definition out of a file-system path.

Folders defined as source folders will be used for the conversion.

Parameters:

	$file	An absolute file-system path to a file.
	$function	The name of a function to be appended.

Returns:: string

Definition at line 353 of file Logger.class.php.

spunQ_Logger::formatFileToPath	(	$	folder,
		$	file
	)			`[private]`

Formats the file between the folder and the file in spunQ's format.

The extension after the first dot in the filename is removed.
Slashes are replaced with dots.

Parameters:

$file

An absolute file-system path to a file.

Returns:: string

Definition at line 373 of file Logger.class.php.

spunQ_Logger::getCaller ( ) [private]

Uses spunQ_Backtrace to find calling function.

All internal functions of the spunQ_Logger are skipped, of course.

Returns:: array Associative array with the keys 'file', 'line' and 'function', either of which can be NULL.

Developer log entry:: Necdet Can Atesman (2009-01-23): The debug_backtrace() provides lines where a function has been called. But we don't need the function that was called, but the function from which the call was made. So we iterate one more time in the foreach to get that function.

Developer log entry:: Necdet Can Atesman (2009-01-26): Switched to the new spunQ_Backtrace class.

Definition at line 442 of file Logger.class.php.

static spunQ_Logger::getInstance ( ) [static]

Retrieves Singleton instance.

Returns:: spunQ_Logger

Definition at line 222 of file Logger.class.php.

spunQ_Logger::getLoggingRules	(	$	path,
		$	priority
	)			`[private]`

Finds the matching rule for the given caller and the given priority.

Parameters:

	$path	The path of the event.
	$priority	The priority with which the Logger was invoked.

Returns:: spunQ_LoggerRule

Definition at line 464 of file Logger.class.php.

spunQ_Logger::info ( $ message )

Log a message with info-level priority.

Parameters:

$message

An arbitrary message - could be an object, too

Returns:: void (logMessage returns void)

Definition at line 285 of file Logger.class.php.

spunQ_Logger::logMessage	(	$	priority,
		$	message
	)

Log a message with arbitrary priority.

Parameters:

	$priority	A priority level
	$message	An arbitrary message - could be an object, too. LogTargets can make use of spunQ_LogTarget::convertObjectToString() in that case.

Returns:: void

Definition at line 323 of file Logger.class.php.

spunQ_Logger::removeRule ( spunQ_LoggerRule $ rule )

Removes a rule from the logger.

Parameters:

$rule

The rule to be removed

See also:: spunQ_Logger
spunQ_LoggerRule

Returns:: spunQ_Logger $this

Definition at line 404 of file Logger.class.php.

spunQ_Logger::setLowestPriority ( ) [private]

Sets the class variable lowestPriorityRule.

Returns:: void

Definition at line 417 of file Logger.class.php.

spunQ_Logger::vdebug ( $ message )

Log a message with debug-level priority.

Parameters:

$message

An arbitrary message - could be an object, too

Returns:: void (logMessage returns void)

Definition at line 267 of file Logger.class.php.

spunQ_Logger::warning ( $ message )

Log a message with warning-level priority.

Parameters:

$message

An arbitrary message - could be an object, too

Returns:: void (logMessage returns void)

Definition at line 294 of file Logger.class.php.

Member Data Documentation

spunQ_Logger::$instance = NULL [static, private]

Singleton instance.

Type:: spunQ_Logger

Definition at line 216 of file Logger.class.php.

spunQ_Logger::$lowestPriorityRule = 100 [private]

Required for speed optimization.

The priority of the lowest priority rule is stored here, so the logger can decide very early whether a log event has the possibility of being processed.

Type:: integer

Definition at line 241 of file Logger.class.php.

spunQ_Logger::$messageStack = 0 [protected]

Amount of messages that are in queue to be logged.

A LogTarget might want to log something, in which case the logger will be re-activated, which might cause an infinite loop. This value gets incremented before a logged message is sent to its designated LogTargets and decremented afterwards to detect such cases.
Once MAX_STACK_SIZE is reached, no further log messages will be accepted - they are discarded silently.

Type:: integer

Definition at line 253 of file Logger.class.php.

const spunQ_Logger::MAX_STACK_SIZE = 10

Maximum number of log messages that shall be in queue.

See also:: $messageStack

Definition at line 210 of file Logger.class.php.

The documentation for this class was generated from the following file:

Logger.class.php


Public Member Functions
	vdebug ($message)
	Log a message with debug-level priority.
	debug ($message)
	Log a message with debug-level priority.
	info ($message)
	Log a message with info-level priority.
	warning ($message)
	Log a message with warning-level priority.
	error ($message)
	Log a message with error-level priority.
	critical ($message)
	Log a message with error-level priority.
	logMessage ($priority, $message)
	Log a message with arbitrary priority.
	addRule (spunQ_LoggerRule $rule)
	Adds a rule to the logger.
	removeRule (spunQ_LoggerRule $rule)
	Removes a rule from the logger.
	clearAllRules ()
	Removes all previously defined rules.
Static Public Member Functions
static	getInstance ()
	Retrieves Singleton instance.
Public Attributes
const	VERBOSE_DEBUG = 0
	The lowest possible log-level.
const	VDEBUG = 0
	Alias for VERBOSE_DEBUG.
const	DEBUG = 10
	Informative level for developers.
const	INFO = 20
	Informative level for users.
const	WARNING = 30
	Level for recoverable errors.
const	ERROR = 40
	Level for unrecoverable errors.
const	CRITICAL = 50
	Level for errors that require immediate attention.
const	MAX_STACK_SIZE = 10
	Maximum number of log messages that shall be in queue.
Protected Member Functions
	__construct ()
	Constructor.
Protected Attributes
	$messageStack = 0
	Amount of messages that are in queue to be logged.
Private Member Functions
	fileToPath ($file, $function=NULL)
	Constructs a path definition out of a file-system path.
	formatFileToPath ($folder, $file)
	Formats the file between the folder and the file in spunQ's format.
	setLowestPriority ()
	Sets the class variable lowestPriorityRule.
	getCaller ()
	Uses spunQ_Backtrace to find calling function.
	getLoggingRules ($path, $priority)
	Finds the matching rule for the given caller and the given priority.
Private Attributes
	$rules = array()
	Rules that have been defined.
	$lowestPriorityRule = 100
	Required for speed optimization.
Static Private Attributes
static	$instance = NULL
	Singleton instance.