Caution: The documentation you are viewing is
for an older version of Zend Framework.
You can find the documentation of the current version at docs.zendframework.com
Overview - Zend_Log
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:
It is important to note that the Log must have at least one Writer. You can add any number of Writers using the Log's addWriter() method.
Alternatively, you can pass a Writer directly to constructor of Log as a shortcut:
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:
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:
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:
Explicitly destroying the log in this way is optional and is performed automatically at PHP shutdown.
The Zend_Log class defines the following priorities:
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 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.
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.
User-defined priorities can be added at runtime using the Log's addPriority() method:
The snippet above creates a new priority, FOO, whose value is '8'. The new priority is then available for logging:
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: timestamp, message, priority, and priorityName.
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 setEventItem() 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.
Zend_Log can also be used to log PHP errors. Calling registerErrorHandler() will add Zend_Log before the current error handler, and will pass the error along as well.
|Name||Error Handler Parameter||Description|
|message||errstr||Contains the error message, as a string.|
|errno||errno||Contains the level of the error raised, as an integer.|
|file||errfile||Contains the filename that the error was raised in, as a string.|
|line||errline||Contains the line number the error was raised at, as an integer.|
|context||errcontext||(optional) An array that points to the active symbol table at the point the error occurred. In other words, errcontext will contain an array of every variable that existed in the scope the error was triggered in. User error handler must not modify error context.|