The ezcLog class records log messages and audit trails to one or multiple writers.
Available writers are:
Extra writers can be added by implementing the ezcLogWriter interface.Use the getMapper() method to get an instance of the ezcLogMapper. The ezcLogMapper classes specifies incoming log messages with the ezcLogFilter. Log messages that are accepted, match with the filter, are sent to the ezcLogWriter.
The following example demonstrates how all log messages, except for the audit trailing and debug messages, are written to a file.
The log messages with the severity: INFO, NOTICE, WARNING, ERROR, and FATAL will be written to the file: "/tmp/logs/error.log". See ezcLogUnixFileWriter for the description of the file format.
The following example will write the audit trails to the database:
The audit trails will be stored in the table "audits". See ezcLogDatabaseWriter for creating the appropriate tables and setting up the database. See the ezcLogFilter for more details.
Use the log() method to log messages at the specified writers. This method expects a:
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.
An example of a Payment checker is as follows:
Sometimes information repeats for specific severities or categories. For example that for the audit trails an username is required. Convenience methods like: setSeverityAttributes() and setSourceAttributes() exist to append information automatically to the log message.
The ezcLog class provides a http://www.php.net/trigger_error log handler: ezcLog::logHandler(). Using the trigger_error method makes your code less Log package dependent and produces less overhead when logging is disabled.
See the ezcLog::logHandler() method for more information about how to set up the trigger_error functionality.
See the ezcDebug package for more detailed information about writing DEBUG messages.
Source for this file: /EventLog/src/log.php
Version: | //autogentag// |
DEBUG
= 1
|
Debug severity constant. |
ERROR
= 64
|
Error severity constant. |
FAILED_AUDIT
= 4
|
Failed audit severity constant. |
FATAL
= 128
|
Fatal severity constant. |
INFO
= 8
|
Info severity constant. |
NOTICE
= 16
|
Notice severity constant. |
SUCCESS_AUDIT
= 2
|
Success audit severity constant. |
WARNING
= 32
|
Warning severity constant. |
string | read/write |
$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. |
string | read/write |
$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. |
protected mixed |
$context
Stores the attributes from the eventTypes and eventSources. $var ezcLogContext |
protected ezcLogFilterSet |
$writers
Contains the logic of mapping an incoming log message to the writer. |
public static ezcLog |
getInstance(
)
Returns the instance of the class. |
public static void |
logHandler(
$errno
, $errstr
, $errfile
, $errline
)
This method can be set as error_handler to log using http://www.php.net/trigger_error. |
public static string |
translateSeverityName(
$severity
)
Translates the severity constant to a string and returns this. |
public ezcLogMapper |
getMapper(
)
Returns an instance of the current ezcLogMapper. |
public void |
log(
$message
, $severity
, [ $attributes
= array()] )
Write the message $message with additional information to one or multiple log writers. |
public void |
reset(
)
Resets the log instance to its initial state. |
protected void |
setDefaults(
)
Sets the source and category defaults to "default". |
public void |
setMapper(
$mapper
)
Sets the given ezcLogMapper $mapper as the log message to writer map. |
public void |
setSeverityAttributes(
$severityMask
, $attributes
)
Sets the attributes $attributes for a group of severities $severityMask. |
public void |
setSourceAttributes(
$sources
, $attributes
)
Sets the attributes $attributes for a group of sources $sources. |
public void |
throwWriterExceptions(
$enable
)
Enables or disables writer exceptions with the boolean $enable. |
Returns the instance of the class.
This method can be set as error_handler to log using http://www.php.net/trigger_error.
This method can be assigned with the http://www.php.net/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:
[ 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.
Notice that the ezcLog component is not loaded at all when the logging is disabled.
Name | Type | Description |
---|---|---|
$errno |
int | |
$errstr |
int | |
$errfile |
string | |
$errline |
int |
Translates the severity constant to a string and returns this.
Null is returned when the severity constant is invalid.
Name | Type | Description |
---|---|---|
$severity |
int |
Returns an instance of the current ezcLogMapper.
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 ezcLogFilter. The following parameters are taken in the comparation with the ezcLogFilter:
The message $message describes what happened. The severity $severity is one of the ezcLog constants:
The methods setSeverityAttributes() and setSourceAttributes() can automatically add attributes to log messages based on, respectively, the severity and source.
See also logHandler() on how to use http://www.php.net/trigger_error to write log messages.
Name | Type | Description |
---|---|---|
$message |
string | |
$severity |
int | One of the following severity constants: DEBUG, SUCCES_AUDIT, FAIL_AUDIT, INFO, NOTICE, WARNING, ERROR, or FATAL. |
$attributes |
array(string=>string) |
Type | Description |
---|---|
ezcLogWriterException |
if throwWriterExceptions are enabled and a log entry could not be written. |
Resets the log instance to its initial state.
All sourceAttributes, severityAttributes, and writers will be removed. The default source and category are also reset.
Sets the source and category defaults to "default".
Sets the given ezcLogMapper $mapper as the log message to writer map.
By default the ezcLogFilterSet is the default writer map. The default ezcLogMapper can be replaced with this method.
Name | Type | Description |
---|---|---|
$mapper |
ezcLogMapper |
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:
Every log message that has the severity SUCCESS_AUDIT or FAILED_AUDIT includes the user name: "Jan K. Doodle".
Name | Type | Description |
---|---|---|
$severityMask |
integer | Multiple severities are specified with a logic-or. |
$attributes |
array(string=>string) |
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:
Every log message that comes from the payment module: Paynet, Bibit, or Paypal includes the Merchant ID.
Name | Type | Description |
---|---|---|
$sources |
array(string) | |
$attributes |
array(string=>string) |
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.
Name | Type | Description |
---|---|---|
$enable |
bool |