Zeta Components - high quality PHP components

• Tutorial
• API

eZ Components - EventLog

Introduction

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.

Class overview

The following classes are most important to use, customize or extend:

ezcLog

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

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

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

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.

ezcLogUnixFileWriter

ezcLogUnixFileWriter writes the log message to a file.

ezcLogFilter

ezcLogFilter is a structure to specify which log messages are accepted in a filter set.

For more information about these classes, see the class documentation.

Examples

Writing a log message to file

This example creates a file writer and assigns it to the default log mapper.

1. <?php
3. require_once 'tutorial_autoload.php';
5. // Get the one and only instance of the ezcLog.
6. $log = ezcLog::getInstance();
8. // Get an instance to the default log mapper.
9. $mapper = $log->getMapper();
11. // Create a new Unix file writer, that writes to the file: "default.log".
12. $writer = new ezcLogUnixFileWriter( "/tmp/logs", "default.log" );
14. // Create a filter that accepts every message (default behavior).
15. $filter = new ezcLogFilter;
17. // Combine the filter with the writer in a filter rule. 
18. $rule = new ezcLogFilterRule( $filter, $writer, true );
20. // And finally assign the rule to the mapper.
21. $mapper->appendRule( $rule ); 
23. // Write a message to the log. 
24. $log->log( "Could not connect with the payment server.", ezcLog::WARNING );
26. ?>

First, tutorial_autoload.php is included. This file loads the correct PHP files for the EventLog component.

Then, the log is set up and a message is written to the log file default.log, to be placed in the /tmp/logs directory.

After execution, the file /tmp/logs/default.log contains something like this:

The date, severity, source, category and message are shown. The source and category are both set to default, because they were not specified in the message.

Writing a log message to a database

With the optional EventLogDatabaseTiein component it is also possible to write log messages to a database table. See the EventLogDatabaseTiein tutorial on how to use the ezcLogDatabaseWriter as writer instead of the ezcLogUnixFileWriter from this component. You can use both log writers at the same time. See the section Assigning log messages to different files on how to use different writers simultaneously.

Assigning sources and categories

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.

1. <?php
3. require_once 'tutorial_autoload.php';
4. date_default_timezone_set( "UTC" );
6. // Same set up as the previous example.
7. $log = ezcLog::getInstance();
8. $writer = new ezcLogUnixFileWriter( "/tmp/logs", "default.log" );
9. $log->getmapper()->appendRule( new ezcLogFilterRule( new ezcLogFilter, $writer, true ) );
11. // Set the source and category.
12. $log->source = "Payment module";
13. $log->category = "Template";
15. $log->log( "Could not find cache file: </var/cache/payment1234.cache>.", ezcLog::WARNING );
17. // ...
19. // Write a SQL error. The category is set to SQL for this message only. 
20. $log->log( "Cannot execute query: <SELECT * FROM Orders WHERE ID = '123'>.", ezcLog::ERROR, array( "category" => "SQL" ) );
22. // ...
24. // Write a debug message that includes the current filename and line number.
25. // The category is left out.
26. $log->log( "Starting shutdown process.", ezcLog::DEBUG, array( "category" => "", "file" => __FILE__, "line" => __LINE__ ) );
28. ?>

After execution, the file /tmp/logs/default.log contains something like this:

Adding log attributes automatically

In some cases, it is convenient to automatically add log attributes to the log message. For example:

• Audit trails should include the current user.

• A payment system should always include the order number.

However, the log attributes appended to the log message are static. The value assigned to the attribute will be the same.

The next example assigns two automatic attributes:

1. <?php
3. require_once 'tutorial_autoload.php';
4. date_default_timezone_set( "UTC" );
6. // Same set up as the previous examples.
7. $log = ezcLog::getInstance();
8. $writer = new ezcLogUnixFileWriter( "/tmp/logs", "default.log" );
9. $log->getmapper()->appendRule( new ezcLogFilterRule( new ezcLogFilter, $writer, true ) );
11. // ...
13. $username = "John Doe";
14. $service = "Paynet Terminal";
16. // ... 
18. // Add automatically the username to the log message, when the log message is either a SUCCESS_AUDIT or a FAILED_AUDIT.
19. $log->setSeverityAttributes( ezcLog::SUCCESS_AUDIT | ezcLog::FAILED_AUDIT, array( "username" => $username ) );
21. // Same can be done with the source of the log message.
22. $log->setSourceAttributes( array( "Payment" ), array( "service" => $service ) );
24. // Writing some log messages.
25. $log->log( "Authentication failed", ezcLog::FAILED_AUDIT, array( "source" => "security", "category" => "login/logoff" ) );
27. $log->source = "Payment"; 
28. $log->log( "Connecting with the server.", ezcLog::DEBUG, array( "category" => "external connections" ) );
30. $log->log( "Paid with credit card.", ezcLog::SUCCESS_AUDIT, array( "category" => "shop" ) );
33. ?>

After execution, the file /tmp/logs/default.log contains this:

Assigning log messages to different files

Depending on the incoming log message, the message can be stored with different writers. This example handles the log message as follows:

• Ignore all messages with the severity DEBUG.

• Store the audit trails in the audit_trails.log file.

• Store the logs with the Payment category in the payment.log file.

• Store all the messages, except DEBUG, in the general.log file.

The code is as follows:

1. <?php
2. require_once 'tutorial_autoload.php';
3. date_default_timezone_set( "UTC" );
5. // Same set up as the previous examples.
6. $log = ezcLog::getInstance();
8. // Create the writers
9. $writeAll = new ezcLogUnixFileWriter( "/tmp/logs", "general.log" );
10. $writePayment = new ezcLogUnixFileWriter( "/tmp/logs", "payment.log" );
11. $writeAuditTrails = new ezcLogUnixFileWriter( "/tmp/logs", "audit_trails.log" );
13. $debugFilter = new ezcLogFilter;
14. $debugFilter->severity = ezcLog::DEBUG;
15. $log->getmapper()->appendRule( new ezcLogFilterRule( $debugFilter, array(), false ) );
17. $auditFilter = new ezcLogFilter;
18. $auditFilter->severity = ezcLog::SUCCESS_AUDIT | ezcLog::FAILED_AUDIT;
19. $log->getMapper()->appendRule( new ezcLogFilterRule( $auditFilter, $writeAuditTrails, true ) );
21. $paymentFilter = new ezcLogFilter;
22. $paymentFilter->source = array( "Payment" );
23. $log->getMapper()->appendRule( new ezcLogFilterRule( $paymentFilter, $writePayment, true ) );
25. $log->getMapper()->appendRule( new ezcLogFilterRule( new ezcLogFilter, $writeAll, true ) );
28. // Writing some log messages.
29. $log->log( "Authentication failed", ezcLog::FAILED_AUDIT, array( "source" => "security", "category" => "login/logoff" ) );
31. $log->source = "Payment"; 
32. $log->log( "Connecting with the server.", ezcLog::DEBUG, array( "category" => "external connections" ) );
34. $log->log( "Paid with credit card.", ezcLog::SUCCESS_AUDIT, array( "category" => "shop" ) );
36. $log->log( "The credit card information is removed.", ezcLog::NOTICE, array( "category" => "shop" ) );
37. ?>

Using trigger_error()

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

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.

1. <?php
2. require_once 'tutorial_autoload.php';
4. class customLazyLogConfiguration implements ezcBaseConfigurationInitializer
5. {
6.     public static function configureObject( $log )
7.     {
8.         $writeAll = new ezcLogUnixFileWriter( "/tmp/logs", "general.log" );
9.         $log->getMapper()->appendRule( new ezcLogFilterRule( new ezcLogFilter, $writeAll, true ) );
10.     }
11. }
13. ezcBaseInit::setCallback( 
14.     'ezcInitLog', 
15.     'customLazyLogConfiguration'
16. );
18. // Use log
19. $log = ezcLog::getInstance();
21. $log->log( "Paid with credit card.", ezcLog::SUCCESS_AUDIT, array( "category" => "shop" ) );
22. $log->log( "The credit card information is removed.", ezcLog::NOTICE, array( "category" => "shop" ) );
23. ?>

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.