Overview
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
objects:
- 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 addWriter()
method.
You can also add a priority to each writer. The priority is specified as an
integer and passed as the second argument in the addWriter()
method.
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
options array).
Logging Messages
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 priority
argument:
$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
If the Logger
instance 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 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
The 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 Zend\Log\Logger
;
PSR-3 uses similar semantics, but without
the explicit priority integers.
Priority numbers descend in order of importance. EMERG
(0) 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 DEBUG
. When
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:
timestamp
message
priority
priorityName
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 unregisterErrorHandler()
static
method.
You can also configure a logger to intercept exceptions using the static method
registerExceptionHandler($logger)
.
Found a mistake or want to contribute to the documentation? Edit this page on GitHub!