Locating the XLOG class file
To use XLOG framework within your application, you first have to import XLOG classes. This is done, in PHP, thru the include_once directive (see sample code here).
The XLOG class files can be located anywhere in the file hierarchy of your program documents. However, when using XLOG within a Web application, don't forget that XLOG writes directly to files which MUST NOT be accessible to a browser agent. So, we recommand to put the XLOG class files in a library directory outside the root directory of the Web server.
For instance, if your Web server root directory is /www/domain/, create a /www/xlog directory and copy the distribution phplib directory and its content in that new directory.
Setting log file path(s)
Then you have to define the path to the log file(s) you will use with XLOG.
Once again, in a Web environment, choose to locate your log files outside your server root directory and, for instance, create a subdirectory in the xlog directory you have previously created to group your log files in /www/xlog/logs/.
The Web server MUST have write permission to the log files.
Using the Logger instance object
You can then instantiate an XLOG_Logger object providing the arguments needed by the class constructor:
• the log file path used with this object,
• the name of the file instantiating the XLOG_Logger object (this is to easily trace the logging source),
• (optionally) the level of logging you want -- in order to, during the development stage, log debugging data, then during production stage only log fatal errors data,
• (optionally) the array defining these logging levels as a hash mapping each logging name with a unique integer level.
To make your life easier, the last two arguments may be disgarded, as default values are provided by XLOG implementation, providing the usual levels of DEBUG, INFO, NOTIFY (warning) and ALERT (fatal error).
Thru the logging levels array, you can define the specific levels of logging your application may need.
Of course, you can have as many log files used simultaneously as you want, if you instantiate several XLOG_Logger objects, but take care of logging with the right logger!
Logging data
Each time you want to log some data to trace your program run, call the logging method of your XLOG_Logger instance with the appropriated arguments:
• the level of logging, corresponding to one of the levels you have provided to your XLOG_Logger instance,
• the data you want to log: this can be any kind of text or, better, a well-balanced XML fragment you will further process,
• (optionally) the name or function calling for a log, to ease logging source retrieval,
• (optionally) the line of the source code where logging is requested (idem).
You can disgard these optional arguments if you don't need them, but tracing the logging source will not be as easy.
Flushing logs to the log file
Finally, you have to actually write to the file log all the logs you have inserted. This has to be done because, to improve logging mechanism performance and avoid too much frequent file access, logs are buffered in an array, waiting that you decide to flush them. So you can flush a bunch of logs with a single log file write.
You do that calling the setOut method, which needs no argument.
If you use XLOG PHP implementation, you can take advantage of the register_shutdown_function to automatically flush the logs buffer when your script is over.
However, this function only accept globally defined functions, so no object method can be passed to it. Therefore, you have to wrap your setOut method with a function whose name is passed to the register_shutdown_function.
A short XLOG PHP sample
<?php
define('PHPLIB_DIR', "/www/xlog/php/");
include_once(PHPLIB_DIR . 'xlog.php');
define('LOG_PATH', '/www/xlog/logs/xlog.xml');
function XLOG_Test_setOut //Logs flushing wrapper function called by register_shutdown_function
(){
global $XLOG_TestLogger;
$XLOG_TestLogger->setOut();
}
$XLOG_TestLevels = array(DEBUG_LOG=>DEBUG_ENABLE, INFO_LOG=>INFO_ENABLE,
NOTIFY_LOG=>NOTIFY_ENABLE, ALERT_LOG=>ALERT_ENABLE);
$XLOG_TestLogger = new XLOG_Logger(LOG_PATH, __FILE__, DEBUG_ENABLE, $XLOG_TestLevels);
register_shutdown_function("XLOG_Test_setOut");
$XLOG_TestLogger->setLog("DEBUG", "Debugging level enable -- no caller and line arguments");
$XLOG_TestLogger->setLog("INFO", "Info level enable -- no line argument", "XLOG_test");
$XLOG_TestLogger->setReportLevel(ALERT_ENABLE);
$XLOG_TestLogger->setLog("NOTIFY", "Notify level enable", "XLOG_test", __LINE__); //not logged
$XLOG_TestLogger->setLog("ALERT", "Alert level enable", "XLOG_test", __LINE__);
?>
With the script above, you end up with a log file (assuming no previous log has been saved to this log file) such as:
<?xml version="1.0" encoding="UTF-8"?>
<xlog:logs xmlns:xlog="http://xlog.sourceforge.net/namespaces/xlog/1.0">
<xlog:report date="2002-08-27@17:10:31" stamp="1030461031.902012" src="www/xlog/test/xlog-test.php">
<xlog:entry category="DEBUG" stamp="1030461031.901611">
<xlog:content>Debugging level enable -- no caller and line arguments</xlog:content>
</xlog:entry>
<xlog:entry category="INFO" stamp="1030461031.901720">
<xlog:caller>XLOG_test</xlog:caller>
<xlog:content>Info level enable -- no line argument</xlog:content>
</xlog:entry>
<xlog:entry category="ALERT" stamp="1030461031.901800">
<xlog:caller>XLOG_test</xlog:caller>
<xlog:line>29</xlog:line>
<xlog:content>Alert level enable</xlog:content>
</xlog:entry>
</xlog:report>
</xlog:logs>
XLOG PHP classes documentation browser
You can browse PHP implementation documentation here.
XLOG XML schema
As you can see from this sample, XLOG schema is very simple:
The root element is the logs element.
Each logs flushing is enclosed by a report element with three attributes:
• the complete date in ISO format (yyyy-mm-dd@hh:mm:ss),
• a stamp (given here in seconds since the UNIX epoch and microseconds),
• the source of the XLOG_Logger instance declaration.
Within each report, each log that have been enabled is enclosed by an entry element with two attributes:
• the entry log level,
• a stamp (in the same format than above).
The log data is enclosed by a content element.
If the log entry caller function or method have been specified in the code, it is enclosed by a caller element.
If the log entry source code line have been provided, it is enclosed by a line element.
For a more formal definition of XLOG structure, have a look at the XML Schema for XLOG.
Extending XLOG XML schema
Every XLOG element uses a specific namespace and prefix (xlog) allowing you to further define elements to structure the xlog:content element (using any other namespace(s) of your choice).
For instance, have a look at the profile sample (xprofile-test.php), which defines a profile namespace and specific elements, taking advantage of XLOG stamping mechanism to build a usefull profiling system whose transformation can be seen here.
The XML log is here.
The XSLT stylesheet is here.
