Zend_Log is a component for general purpose logging.
It supports multiple log backends, formatting messages sent to the log,
and filtering messages from being logged. These functions are divided
into the following objects:
A Log (instance of
Zend_Log) is the object that your application uses the most. You can have as many Log objects as you like; they do not interact. A Log object must contain at least one Writer, and can optionally contain one or more Filters.
A Writer (inherits from
Zend_Log_Writer_Abstract) is responsible for saving data to storage.
A Filter (implements
Zend_Log_Filter_Interface) blocks log data from being saved. A filter may be applied to an individual Writer, or to a Log where it is applied before all Writers. In either case, filters may be chained.
A Formatter (implements
Zend_Log_Formatter_Interface) can format the log data before it is written by a Writer. Each Writer has exactly one Formatter.
To get started logging, instantiate a Writer and then pass it to a Log instance:
$logger = new Zend_Log(); $writer = new Zend_Log_Writer_Stream('php://output'); $logger->addWriter($writer);
It is important to note that the Log must
have at least one Writer. You can add any number of Writers using the
Alternatively, you can pass a Writer directly to constructor of Log as a shortcut:
$writer = new Zend_Log_Writer_Stream('php://output'); $logger = new Zend_Log($writer);
The Log is now ready to use.
To log a message, call the
log() method of a Log instance
and pass it the message with a corresponding priority:
$logger->log('Informational message', Zend_Log::INFO);
The first parameter of the
log() method is a string
message and the second
parameter is an integer
priority. The priority must be one of the priorities recognized
by the Log instance. This is explained in the next section.
A shortcut is also available. Instead of calling the
log() method, you can
call a method by the same name as the priority:
$logger->log('Informational message', Zend_Log::INFO); $logger->info('Informational message'); $logger->log('Emergency message', Zend_Log::EMERG); $logger->emerg('Emergency message');
If the Log object is no longer needed, set the variable containing it to
NULL to destroy it. This will automatically call the
shutdown() instance method of each attached Writer before
the Log object is destroyed:
$logger = null;
Explicitly destroying the log in this way is optional and is performed automatically at PHP shutdown.
Zend_Log class defines the following priorities:
EMERG = 0; // Emergency: system is unusable ALERT = 1; // Alert: action must be taken immediately CRIT = 2; // Critical: critical conditions ERR = 3; // Error: error conditions WARN = 4; // Warning: warning conditions NOTICE = 5; // Notice: normal but significant condition INFO = 6; // Informational: informational messages DEBUG = 7; // Debug: debug messages
These priorities are always available, and a convenience method of the same name is available for each one.
The priorities are not arbitrary. They come from the BSD
which is described in RFC-3164.
The names and corresponding priority numbers are also
compatible with another PHP logging system,
which perhaps promotes interoperability between it and
Priority numbers descend in order of importance.
is the most important priority.
DEBUG (7) is the least
important priority of the built-in priorities. You may define priorities
of lower importance than
selecting the priority for your log message, be aware of this priority
hierarchy and choose appropriately.
User-defined priorities can be added at runtime using the Log's
The snippet above creates a new priority,
8. The new priority is then available for logging:
$logger->log('Foo message', 8); $logger->foo('Foo Message');
New priorities cannot overwrite existing ones.
When you call the
log() method or one of its shortcuts, a
log event is created. This is simply an associative array with data
describing the event that is passed to the writers. The following keys
are always created in this array:
The creation of the
event array is completely transparent.
However, knowledge of the
event array is required for adding an
item that does not exist in the default set above.
To add a new item to every future event, call the
method giving a key and a value:
The example above sets a new item named
pid and populates
it with the PID of the current process. Once a new item has been
set, it is available automatically to all writers along with all of the
other data event data during logging. An item can be overwritten at any
time by calling the
setEventItem() method again.
Setting a new event item with
setEventItem() causes the
new item to be sent to all writers of the logger. However, this does
not guarantee that the writers actually record the item. This is
because the writers won't know what to do with it unless a formatter
object is informed of the new item. Please see the section on Formatters
to learn more.