* $filter = new ezcLogFilter();
* $filter->severity = ezcLog::INFO | ezcLog::NOTICE | ezcLog::WARNING | ezcLog::ERROR | ezcLog::FATAL;
*
* $log = ezcLog::getInstance();
* $log->map( $filter, new ezcLogWriterUnixFile( "/tmp/logs/", "error.log" ) );
*
*
* The log messages with the severity: INFO, NOTICE, WARNING, ERROR, and FATAL will
* be written to the file: "/tmp/logs/error.log". See {@link ezcLogWriterUnixFile} for
* the description of the file format.
*
* The following example will write the audit trails to the database:
*
* $filter = new ezcLogFilter();
* $filter->severity = ezcLog::SUCCESS_AUDIT | ezcLog::FAILED_AUDIT;
*
* $log = ezcLog::getInstance();
* $log->map( $filter, new ezcLogWriterDatabase( "audits" ) );
*
*
* The audit trails will be stored in the table "audits". See {@link ezcLogWriterDatabase}
* for creating the appropriate tables and setting up the database.
*
* It is also possible to exclude messages from going to a specific writer.
* This is done via the {@link unmap()} method. The following example shows
* how all messages, except for the DEBUG severity, are written to a file:
*
* $fileWriter = ezcLogWriterUnixFile( "/tmp/logs/", "all.log" );
* $filter = new ezcLogFilter();
* $ezcLog::getInstance()->map( $filter, $fileWriter ); // All severities.
*
* $filter->severity = ezcLog::DEBUG;
* ezcLog::getInstance()->unmap( $filter, $fileWriter ); // Remove DEBUG severity.
*
*
* Use the {@link log()} method to log messages at the specified writers. This
* method expects a:
* - Message, contains a single log message.
* - Severity, indicates the level of importance.
* - Extra attributes (optional).
*
* Although the interpretation of the severity levels are up to the programmer,
* the most common interpretations are:
* - DEBUG: Records information about the progress in the program and references
* source code functions. Knowledge of the source code is needed to interpret
* this log message.
* - INFO: Informative logging at a detailed level. This logging method produces a
* high level of logging, which is unmanageable on a production environment.
* Usually INFO logging is only enabled to help by analysing a problem.
* - NOTICE: Informative logging at a lower detail level than INFO logging.
* Only major stages are recorded and is useful to monitor a low volume system.
* - WARNING: Something unexpected happened, but did not cause any loss of service.
* - ERROR: An error occured, which may cause partial loss of service. Usually the
* system can recover.
* - FATAL: An serious error occured and the system is unlikely to recover.
* - SUCCESS_AUDIT: Informative logging about a successful completion of work by
* a module completed. Useful to trace system changes directly or indirectly
* done by a user.
* - FAILED_AUDIT: Informative logging about an action from a module
* with a negative result. A failed login will most likely added to this severity.
*
* The next example logs a fatal error and has no extra attributes:
*
* ezcLog::getInstance()->log( "Cannot open ini file: <$file>", ezcLog::FATAL );
*
*
* The log message will get by default the category and source: "default". The
* default values can be modified by changing, respectively, the properties:
* category and source. Their use is as follows:
* - Source, definition of the global location where the log message comes from.
* Some examples are: module, source file, extension, etc. The source depends
* also on the severity of the message. For DEBUG messages is the source file
* more important whereas for a FATAL error the module is sufficient.
* - Category, definition of the message group. Again the category is related to
* the severity. The non audit trails can group the log messages like: Database
* (or even the database types), Templates, etc. For audit trails it makes
* much sense to categorize the actions. For example: security, modified content,
* published content, shop, etc.
*
* An example of a Payment checker is as follows:
*
* // The start of the Payment module.
* $log = ezcLog::getInstance();
* $log->source = "Payment checker"; // Change the default source.
*
* $log->log( "Checking the received amount", ezcLog::INFO, array( "shop" ) );
*
* if( !$eZPay->receivedAmount() != $requiredAmount )
* {
* $log->log( "Received amount: <".$eZPay->receivedAmount()."> expected: <$requiredAmount>.",
* ezcLog::DEBUG,
* array( "category" => "shop", "file" => __FILE__, "line" => __LINE )
* );
*
* $log->log( "Insufficient amount.",
* ezcLog::FAILED_AUDIT,
* array( "UserName" => getCurrentUser(), category => "Payment" )
* )
*
* $log->log( "Rollback amount not implemented, cannot recover, ezcLog::FATAL );
* exit();
* }
*
*
* Sometimes information repeats for specific severities or categories. For example that
* for the audit trails an username is required. Convenience methods like:
* {@link setSeverityAttributes()} and {@link setSourceAttributes()} exist to append
* information automatically to the log message.
*
* The ezcLog class provides a {@link trigger_error()} log handler: {@link ezcLog::LogHandler()}.
* Using the trigger_error method makes your code less Log package dependent and
* produces less overhead when logging is disabled.
*
* See the {@link ezcLog::LogHandler()} method for more information about how to set up the
* trigger_error functionality.
*
* See the {@link ezcDebug} package for more detailed information about writing DEBUG
* messages.
*
* @package EventLog
* @version //autogentag//
*/
class ezcLog
{
/**
* Debug severity constant.
*/
const DEBUG = 1;
/**
* Success audit severity constant.
*/
const SUCCESS_AUDIT = 2;
/**
* Failed audit severity constant.
*/
const FAILED_AUDIT = 4;
/**
* Info severity constant.
*/
const INFO = 8;
/**
* Notice severity constant.
*/
const NOTICE = 16;
/**
* Warning severity constant.
*/
const WARNING = 32;
/**
* Error severity constant.
*/
const ERROR = 64;
/**
* Fatal severity constant.
*/
const FATAL = 128;
/**
* Holds the properties of this class.
*
* @var array(string=>mixed)
*/
private $properties = array();
/**
* Contains the logic of mapping an incoming log message to the writer.
*
* @var ezcLogMap
*/
protected $writers;
/**
* Stores the attributes from the eventTypes and eventSources.
*
* $var ezcLogContext
*/
protected $context;
/**
* Stores the instance of this class.
*
* @var ezcLog
*/
private static $instance = null;
/**
* Stores the setting whether writer exceptions should be thrown.
*
* @var bool
*/
private $throwWriterExceptions = true;
/**
* Constructs an empty ezcLog instance.
*
* This constructor is private as this class should be used as a
* singleton. Use the getInstance() method instead to get an ezcLog instance.
*/
private function __construct()
{
$this->reset();
}
/**
* Returns the instance of the class.
*
* @return ezcLog
*/
public static function getInstance()
{
if ( is_null( self::$instance ) )
{
self::$instance = new self();
}
return self::$instance;
}
/**
* Sets the property $name to $value.
*
* @throws ezcBasePropertyNotFoundException if the property does not exist.
* @param string $name
* @param mixed $value
* @return void
*/
public function __set( $name, $value )
{
switch ( $name )
{
case "source":
case "category":
$this->properties[$name] = $value;
return;
}
throw new ezcBasePropertyNotFoundException( $name );
}
/**
* Returns the property $name.
*
* @throws ezcBasePropertyNotFoundException if the property does not exist.
* @param string $name
* @return mixed
*/
public function __get( $name )
{
switch ( $name )
{
case "source":
case "category":
return $this->properties[$name];
}
throw new ezcBasePropertyNotFoundException( $name );
}
/**
* Resets the log instance to its initial state.
*
* All sourceAttributes, severityAttributes, and writers will be removed.
* The default source and category are also reset.
*
* @return void
*/
public function reset()
{
$this->writers = new ezcLogMap();
$this->context = new ezcLogContext();
$this->setDefaults();
}
/**
* Sets the source and category defaults to "default".
*
* @return void
*/
protected function setDefaults()
{
$this->source = "default";
$this->category = "default";
}
/**
* Enables or disables writer exceptions with the boolean $enable.
*
* Typically you want to have exceptions enabled while developing your application
* in order to catch potential problems. A live server however, should not throw
* a deadly exception when a relatively unimportant debug message could not be written to
* the log file. For these setups you can disable writer exceptions.
*
* @param bool $enable
* @return void
*/
public function throwWriterExceptions( $enable )
{
$this->throwWriterExceptions = $enable;
}
/**
* Write the message $message with additional information to one or multiple log writers.
*
* The log message $message, severity $severity, and extra attributes $attributes are sent to
* the writers that matches with the {@link ezcLogFilter}. The following parameters are
* taken in the comparation with the ezcLogFilter:
* - $severity: the severity of the log message.
* - $attributes[ "source" ]: the source from where the log message comes.
* - $attributes[ "category" ]: the category of the log message.
*
* See for more information about filter matching the classes {@link ezcLog} and
* {@link ezcLogFilter}.
*
* The message $message describes what happened. The severity $severity is one of the ezcLog constants:
* - DEBUG: Records information about the progress in the program and references
* source code functions. Knowledge of the source code is needed to interpret
* this log message.
* - INFO: Informative logging at a detailed level. This logging method produces a
* high level of logging, which is unmanageable on a production environment.
* Usually INFO logging is only enabled to help by analysing a problem.
* - NOTICE: Informative logging at a lower detail level than INFO logging.
* Only major stages are recorded and is useful to monitor a low volume system.
* - WARNING: Something unexpected happened, but did not cause any loss of service.
* - ERROR: An error occured, which may cause partial loss of service. Usually the
* system can recover.
* - FATAL: An serious error occured and the system is unlikely to recover.
* - SUCCESS_AUDIT: Informative logging about a successful completion of work by
* a module completed. Useful to trace system changes directly or indirectly
* done by a user.
* - FAILED_AUDIT: Informative logging about an action from a module
* with a negative result. A failed login will most likely added to this severity.
*
* The attributes array $attributes can have one or multiple attributes that will
* be added to the log. If source and category are given, they will override the default
* source or category given as property to this object. Further more it is up to the
* application what to include in the log. It may be useful to add the
* file and linenumber to the attributes array. Use the magic PHP constants: {@link __FILE__}
* and {@link __LINE__} for this purpose. The next example adds an warning to the log.
*
*
* ezcLog::getInstance()->source = "templateEngine"; // Set the default source.
* ezcLog::getInstance()->log( "ezcPersistentObject <$obj> does not exist.",
* ezcLog::WARNING,
* array( "category" => "Database", "line" => __LINE__, "file" => __FILE__, "code" => 123 )
* );
*
*
* The methods {@link setSeverityAttributes()} and {@link setSourceAttributes()} can automatically
* add attributes to log messages based on, respectively, the severity and source.
*
* See also {@link LogHandler()} on how to use {@link trigger_error()} to write log messages.
*
* @throws ezcLogWriterException if {@link throwWriterExceptions} are enabled and a log entry
* could not be written.
*
* @param string $message
* @param int $severity One of the following severity constants:
* DEBUG, SUCCES_AUDIT, FAIL_AUDIT, INFO, NOTICE, WARNING, ERROR, or FATAL.
* @param array(string=>string) $attributes
* @return void
*/
public function log( $message, $severity, $attributes = array() )
{
$source = ( isset( $attributes["source"] ) ? $attributes["source"] : $this->properties["source"] );
$category = ( isset( $attributes["category"] ) ? $attributes["category"] : $this->properties["category"] );
unset( $attributes["source"] );
unset( $attributes["category"] );
$writers = $this->writers->get( $severity, $source, $category );
foreach ( $writers as $writer )
{
try
{
$writer->writeLogMessage( $message, $severity, $source, $category, $attributes );
}
catch ( ezcLogWriterException $e )
{
if ( $this->throwWriterExceptions )
{
throw $e;
}
}
}
}
/**
* Attaches the writer $writer with the filter $logFilter to this ezcLog.
*
* The log filter $logFilter describes which severities, categories, and
* sources are accepted by the writer $writer. Those messages that
* match are send to the writer.
*
* Multiple logFilters with their writer can be attached to the ezcLog class.
* Every log message will be sent to the writer for which the log filter matches.
*
* Available writers are:
* - {@link ezcLogWriterUnixFile Unix File} writer
* - {@link ezcLogWriterDatabase Database} writer
*
* Extra writers can be added by implementing the the {@link ezcLogWriter} interface.
*
* The following example maps the Unix file writer to all the log messages that
* are from the category "template", source "content_module" and severities
* WARNING, ERROR, or FATAL.
*
* $f = new ezclogFilter();
* $f->severity = ezcLog::WARNING | ezcLog::ERROR | ezcLog::FATAL;
* $f->source = "template";
* $f->category = "content_module";
*
* $w = new ezcLogWriterUnixFile("/tmp/logs/content_module/", "template.log" );
*
* $ezcLog::getInstance()->map( $f, $w );
*
*
* See also {@link unmap()}
*
* @param ezcLogFilter $logFilter
* @param ezcLogWriter $writer
* @return void
*/
public function map( ezcLogFilter $logFilter, ezcLogWriter $writer )
{
$this->writers->map( $logFilter->severity, $logFilter->source, $logFilter->category, $writer );
}
/**
* Detaches the writer $writer for specific log messages, specified by the log filter $logFilter.
*
* The log filter $logFilter describes which severities, categories, and
* sources are no longer accepted by the writer $writer.
*
* See the {@link map()} method for information about attaching a filter.
*
* The following example shows how to log all messages, except the debug message:
*
* $fileWriter = ezcLogWriterUnixFile( "/tmp/logs/", "all.log" );
* $filter = new ezcLogFilter();
* $ezcLog::getInstance()->map( $filter, $fileWriter ); // All severities.
*
* $filter->severity = ezcLog::DEBUG;
* ezcLog::getInstance()->unmap( $filter, $fileWriter ); // Remove DEBUG severity.
*
*
* See also {@link map()}
*
* @param ezcLogFilter $logFilter
* @param ezcLogWriter $writer
* @return void
*/
public function unmap( ezcLogFilter $logFilter, ezcLogWriter $writer )
{
$this->writers->unmap( $logFilter->severity, $logFilter->source, $logFilter->category, $writer );
}
/**
* Sets the attributes $attributes for a group of severities $severityMask.
*
* The severities are specified with a bit mask. These attributes will be
* added to the log message when the log severity is the same as specified
* here.
*
* Example:
*
* ezcLog::getInstance()->setSeverityAttributes(
* ezcLog::SUCCESS_AUDIT | ezcLog::FAILED_AUDIT
* array( "username" => "Jan K. Doodle" )
* );
*
*
* Every log message that has the severity SUCCESS_AUDIT or FAILED_AUDIT
* includes the user name: "Jan K. Doodle".
*
* @param integer $severityMask Multiple severities are specified with a logic-or.
* @param array(string=>string) $attributes
* @return void
*/
public function setSeverityAttributes( $severityMask, $attributes )
{
$this->context->setSeverityContext( $severityMask, $attributes );
}
/**
* Sets the attributes $attributes for a group of sources $sources.
*
* The sources are specified in an array. These attributes will be added to the
* log message when it matches with the given $sources.
*
* Example:
*
* ezcLog::getInstance()->setSourceAttributes(
* array( "Paynet", "Bibit", "Paypal" ),
* array( "MerchantID" => $merchantID )
* );
*
*
* Every log message that comes from the payment module: Paynet, Bibit, or Paypal
* includes the Merchant ID.
*
* @param array(string) $sources
* @param array(string => string) $attributes
* @return void
*/
public function setSourceAttributes ( $sources, $attributes )
{
$this->context->setSourceContext( $sources, $attributes );
}
/**
* This method can be set as error_handler to log using {@link trigger_error()}.
*
* This method can be assigned with the {@link set_error_handler()} to handle the
* trigger_error calls. This method will get the log instance and forward the
* message. But includes the following information:
* - The file and linenumber are automatically added.
* - Source and category can be 'encoded' in the message.
*
* The message format is as follows:
*
* [ source, category ] Message ** * When one name is given between the brackets, the category will be set and the message has a default source: *
* [ category ] Message ** * Without any names between the brackets, the default category and source are used: *
* Message ** * The following example creates manually an error handler and forwards the * ERROR, WARNING and NOTICE severities. *
* public function MyLogHandler($errno, $errstr, $errfile, $errline)
* {
* switch ($errno)
* {
* case E_USER_ERROR:
* case E_USER_WARNING:
* case E_USER_NOTICE:
* if ( $loggingEnabled )
* { // Forward the message to the log handler.
* ezcLog::LogHandler( $errno, $errstr, $errfile, $errline );
* }
* break;
*
* default:
* print( "$errstr in $errfile on line $errline\n" );
* break;
* }
* }
*
* // Register MyLogHandler
* set_error_handler( "MyLogHandler" );
*
* // Write an warning to the log.
* trigger_error( "[paynet, transaction] Didn't get a callback from the Paynet service", E_USER_WARNING );
*
* // Add a notice.
* trigger_error( "Getting paynet status information", E_USER_NOTICE );
*
*
*
* Notice that the ezcLog component is not loaded at all when the logging is disabled.
*
* @param int $errno
* @param int $erstr
* @param string $errfile
* @param int $errline
* @return void
*/
public static function logHandler( $errno, $errstr, $errfile, $errline )
{
$log = ezcLog::getInstance();
$lm = new ezcLogMessage( $errstr, $errno, $log->source, $log->category );
$log->log(
$lm->message, $lm->severity,
array( "source" => $lm->source, "category" => $lm->category, "file" => $errfile, "line" => $errline )
);
}
/**
* Translates the severity constant to a string and returns this.
*
* Null is returned when the severity constant is invalid.
*
* @param int $severity
* @return string
*/
public static function translateSeverityName( $severity )
{
switch ( $severity )
{
case self::DEBUG: return "Debug";
case self::SUCCESS_AUDIT: return "Success audit";
case self::FAILED_AUDIT: return "Failed audit";
case self::INFO: return "Info";
case self::NOTICE: return "Notice";
case self::WARNING: return "Warning";
case self::ERROR: return "Error";
case self::FATAL: return "Fatal";
default: return null;
}
}
}
?>