The Debug component provides an API to log and time debug events. This
component depends mainly on the EventLog. The functionality of the Debug
component is devided in two parts:
- Writing debug messages.
- Measuring the execution time.
Writing a debug message is almost the same as writing a message with the
EventLog. However, there is one major distinction. Messages written with the
EventLog are supposed to be written to a storage (log files, database, etc).
Messages written with the Debug component are usually directly formatted and
displayed. Note that the Debug::log() method has a slightly different signature
than the EventLog::log() method.
Timing information is captured by starting and stopping timers using the public
methods from ezcDebug. The timing information is stored in a structure with raw
data. This structure should be formatted and displayed at the end of the
script.
The Debug summary output can be formatted with an implementation from
ezcDebugOutputFormatter. The default, and currently only, implementation of a
formatter is ezcDebugHtmlFormatter. This HTML formatter transforms the raw log
messages and raw timing information in a HTML string. This HTML string can be
displayed at the end of each HTML page (generated by a PHP script).
The following classes are most important to use, extend, or implement:
- ezcDebug
- Provides the public API for writing Debug messages and capturing timing
information.
- ezcDebugOutputFormatter
- The ezcDebugOutputFormatter provides an interface for the debug output
format. New implementations can format the raw log messages and timing
information in any output format.
- ezcDebugHtmlFormatter
- ezcDebugHtmlFormatter is an implementation from the ezcDebugOutputFormatter
interface. This formatter reads the raw log and timing information and
returns it as a string with a HTML layout. This string can be output directly
in the HTML page.
See class documentation for more information.
The following script writes a message to the Debug component. At the end of the
script the log message is formatted and printed.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4. date_default_timezone_set( "UTC" );
5.
6. // Get the one and only instance of the ezcDebug.
7. $debug = ezcDebug::getInstance();
8.
9. // Write a log message with verbosity 1.
10. $debug->log( "Connecting with the Payment server", 1 );
11.
12. $debug->log( "Connected with the Payment server", 2, array( "source" => "shop", "category" => "payment" ) );
13.
14. // Get HTML output.
15. $output = $debug->generateOutput();
16.
17. echo $output;
18. ?>
Writing log messages is almost the same as writing them to the EventLog. As a
matter of fact, the EventLog is internally used.
Further information about writing log messages can be found in the EventLog
component.
The timers from ezcDebug can be used for two purposes:
- Timers, measure the time between two points in the program.
- Accumulators, get the current time after a certain point (for example after
starting the script)
Both methods are executed with ezcDebug::startTimer(), ezcDebug::stopTimer(),
and ezcDebug::switchTimer(). The next script demonstrates the usage of these
methods:
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4. date_default_timezone_set( "UTC" );
5.
6. // Get the one and only instance of the ezcDebug.
7. $debug = ezcDebug::getInstance();
8.
9. // Start the accumulator.
10. $debug->startTimer( "Program runtime", "Accumulators" );
11. $debug->switchTimer( "Start", "Program runtime" );
12.
13. // Measure the time of writing "hello world".
14. // The name of the timer is: "Hello world" and it will be placed in the group: "output".
15. $debug->startTimer ("Hello world", "output" );
16. echo "Hello world<br/>";
17. $debug->stopTimer( "Hello world" );
18.
19. // Replace the "Start" timer for "Half the way".
20. $debug->switchTimer( "Half the way", "Start" );
21.
22. // Measure the time of writing "cruel world".
23. $debug->startTimer( "Goodbye cruel world", "output" );
24. echo "Goodbye cruel world<br/>";
25. $debug->stopTimer( "Goodbye cruel world" );
26.
27. // Stop the last timer.
28. $debug->switchTimer( "Stop", "Half the way" );
29. $debug->stopTimer( "Stop" );
30.
31. // Get HTML output.
32. $output = $debug->generateOutput();
33.
34. echo "<br/><br/>";
35. echo $output;
36. ?>
The output looks like:
The output has two groups: output and accumulators. In the group "output" are
two timers: "Hello world" and "Goodbye cruel world".
The "accumulators" group has one timer, which is called "Program runtime". This
timer took in total: 0.00034 seconds. In this timer are several "switch
timers". These show the time since the "Program runtime" was started.
Sometimes a specific code block repeats. For example to measure the time a
PHP statement takes in a loop. The Debug timer will calculate the avarage time
of the repeative statement and display it in the debug summary. See the next
script:
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4. date_default_timezone_set( "UTC" );
5.
6. // Get the one and only instance of the ezcDebug.
7. $debug = ezcDebug::getInstance();
8.
9. // Start the accumulator.
10. $debug->startTimer( "Script runtime", "Accumulators" );
11.
12. // Store the name of the accumulator.
13. $accumulatorName = "start";
14. $debug->switchTimer( $accumulatorName, "Script runtime" );
15.
16. // Time the loop.
17. $debug->startTimer ( "Five times Hello world", "output" );
18. for( $i = 0; $i < 5; $i++ )
19. {
20. // Time the "Hello world" only.
21. $debug->startTimer ( "Hello world", "output" );
22. echo "Hello world<br/>";
23. $debug->stopTimer( "Hello world" );
24.
25. // Store the accumulator.
26. $debug->switchTimer( "After: hello world", $accumulatorName );
27. $accumulatorName = "After: hello world";
28. }
29. $debug->stopTimer( "Five times Hello world" );
30.
31. // Stop the accumulator
32. $debug->switchTimer( "stop", $accumulatorName );
33. $debug->stopTimer( "stop" );
34.
35. // Get HTML output.
36. $output = $debug->generateOutput();
37.
38. echo "<br/><br/>";
39. echo $output;
40.
41. ?>
And the output is as follows:
