The EventLog component provides an API to log events and audit trails with log
messages. These log messages are written to files or other storage elements.
How and where the log messages are written depends on the log writer.

The available log writers are:

ezcLogUnixFileWriter, which writes log messages to a file in a Unix file
format.

ezcLogSyslogWriter, which writes log messages to syslog.

ezcLogDatabaseWriter, which writes log messages to the database. This is
available in the EventLogDatabaseTieIn component.

Each of these writers can be customized or extended.

An incoming log message can be written with zero or more writers. The writers
depend on the variables of the log message itself and the
ezcLogMapper implementation. ezcLogMapper checks the
severity, source and category from the log message and forwards the message
to the appropriate writers.

The ezcLog class is a singleton, meaning that only one instance of it can
exist. This class provides methods to configure and record log messages. The
recorded log messages are sent to an implementation of ezcLogMapper, which
forwards the messages to the appropriate log writers.

ezcLogMapper provides an interface for log message mapping. Log
messages are dispatched from ezcLog to a writer. The particular writer is
determined in the class that implements
ezcLogMapper and is assigned in ezcLog.

ezcLogFilterSet is an implementation of ezcLogMapper. ezcLogFilterSet
contains a set of rules in the form of objects of the class ezcLogFilterRule.
These rules are processed sequentially. In other words, the first assigned
rule will be processed first. Each rule determines whether the log message
matches the filter rule. If the log message matches, it calls the writer and
decide whether the filter set stops processing.

The ezcLogFilterSet class is inspired by modern mail application filter
settings. Normally these mail filter settings sort the incoming
mail and store it in the correct mail folder.

ezcLogWriter provides an interface for the writers. An implementation
of this interface is a valid writer and can be addressed by ezcLogMapper.
The writer itself determines how and where the log message is stored.

The default source and category from ezcLog can be set via the properties
source and category. The next example demonstrates how the default
properties can be set and how extra variables can be added to the log.

The EventLog component is designed so that it can also be used with the
trigger_error PHP method. Instead of calling the ezcLog::getInstance()->log() method,
trigger_error() can be called. Using the trigger_error() method makes your code
less dependent on the EventLog component and requires less overhead when
logging is disabled.

The function set_error_handler should set up a callback function (or method)
that, in turn, calls EventLog. For more information, see the API documentation
on the ezcLog::logHandler() method.

Lazy initialization is a mechanism to load and configure a component, only
when it is really used in your application. This mechanism saves time for
parsing the classes and configuration, when the component is not used at all
during one request. You can find a description how you can use it for your
own components and how it works in the ezcBase tutorial. The keyword for
the event log component is ezcInitLog.

The example shows a very simple event log setup with only one single logging
rule. The main difference compared with earlier examples is, that we roll out
the configuration to an own class, and define a callback using
ezcBaseInit::setCallback to this class, which will be called with the
event log instance on the first request for a yet uninitialized log handler.

ezcBaseInit::setCallback accepts as a first parameter a component specific key,
which lets the component later request the right configuration callback. The
second parameter is the name of the class to perform the static callback on.
This class must implement the ezcBaseConfigurationInitializer class.
Each component's lazy initialization calls the static method configureObject()
on the referenced class.

When the event log is really required in the application, like shown in line
19 of the example, the event log component will be configured by the code in
the configureObject() method in line 6, which just add a general logging rule,
writing all log messages to /tmp/logs/general.log.