Zend\Log\Logger 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
- A logger (instance of
Zend\Log\Logger) is the object that your application uses the most. You can have as many logger objects as you like; they do not interact. A logger object must contain at least one writer, and can optionally contain one or more filters.
- A writer (inherits from
Zend\Log\Writer\AbstractWriter) writes data to an underlying storage implementation.
- A filter (implements
Zend\Log\Filter\FilterInterface) filters (blocks) log data from being saved. A filter is applied to an individual writer. Filters can be chained.
- A formatter (implements
Zend\Log\Formatter\FormatterInterface) formats the log data before it is written by a writer. Each writer has exactly one formatter.
- A processor (implements
Zend\Log\Processor\ProcessorInterface) processes the log event prior to filtering or writing, allowing the ability to substitute, add, remove, or modify data to be logged.
Creating a Log
To get started logging, instantiate a writer and then pass it to a logger instance:
$logger = new Zend\Log\Logger; $writer = new Zend\Log\Writer\Stream('php://output'); $logger->addWriter($writer);
It is important to note that the logger must have at least one writer. You can
add any number of writers using the logger's
You can also add a priority to each writer. The priority is specified as an
integer and passed as the second argument in the
Another way to add a writer to a logger is to use the name of the writer as follow:
$logger = new Zend\Log\Logger; $logger->addWriter('stream', null, ['stream' => 'php://output']);
In this example we passed the stream
php://output as a parameter (via an
To log a message, call the
log() method of a
Logger instance and pass it the
message priority and the message:
$logger->log(Zend\Log\Logger::INFO, 'Informational message');
The first parameter of the
log() method is the integer
priority and the
second parameter is the string
message. The priority must be one of the
priorities recognized by the
Logger instance (explained in the next section).
There is also an optional third parameter used to pass extra
information/metadata to the writer.
Instead of using the
log() method, you can optionally call methods named after
the various supported priorities, which allows you to omit the
$logger->log(Zend\Log\Logger::INFO, 'Informational message'); $logger->info('Informational message'); $logger->log(Zend\Log\Logger::EMERG, 'Emergency message'); $logger->emerg('Emergency message');
Destroying a Log
Logger instance is no longer needed, set the variable containing it to
NULL to destroy it. This will automatically call the
method of each attached writer before the
Logger instance is destroyed.
$logger = null;
Explicitly destroying the log in this way is optional and is performed automatically at PHP shutdown.
Using Built-in Priorities
Zend\Log\Logger 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 (but lowercased) is available for each one.
The priorities are not arbitrary. They come from the BSD syslog protocol, which
is described in RFC-3164. The names and
corresponding priority numbers are also compatible with another PHP logging
system, PEAR Log, which perhaps promotes
interoperability between it and
PSR-3 uses similar semantics, but without
the explicit priority integers.
Priority numbers descend in order of importance.
EMERG (0) is the most
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.
Understanding Log Events
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 an internal detail of implementation.
Log PHP Errors
Zend\Log\Logger can also be used to log PHP errors and intercept exceptions.
Calling the static method
registerErrorHandler($logger) will register the
$logger instance to log errors; it returns a boolean
false ensuring that it
returns delegation to any other error handlers registered, including the default
PHP error handler.
$logger = new Zend\Log\Logger; $writer = new Zend\Log\Writer\Stream('php://output'); $logger->addWriter($writer); Zend\Log\Logger::registerErrorHandler($logger);
If you want to unregister the error handler, can use the
You can also configure a logger to intercept exceptions using the static method
Found a mistake or want to contribute to the documentation? Edit this page on GitHub!