Path

ez components / documentation / api reference / 2007.2.1 / debug

eZ Components 2007.2.1

Debug: ezcDebug

[ Tutorial ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcDebug

The ezcDebug class provides functionality to format and store debug messages and timers. [source]
The functionality of the Debug component is two folded:
  • Debug log messages
  • Timers
The log messages are heavily based on the EventLog log messages. In fact internally the EventLog is used with its own log writer. The log() method is almost the same as from the EventLog. The next example demonstrates how to instantiate the ezcDebug class and write some log messages: 
1.  $debug = ezcDebug::getInstance();
2.  $debug->log( "Connecting with the paynet server", 2 );
3.  // ...
4.   $debug->log( "Connection failed, retrying in 5 seconds", 1 );
5.  // ...
6.   $debug->log( "Could not connect with the server", 0 );
The second parameter of the log method is the verbosity. This is a number that specifies the importance of the log message. That makes it easier to sort out messages of less importance. In this example, we assumed the more important the message, the lower the verbosity number.
The ezcDebug timer is designed to allow the next two timing methods:
  • Timers, the time between two points in the program.
  • Accumulators, gets the relative time after the script started.
The "Timers" are simply set with the methods startTimer() and stopTimer(). The next example demonstrates the timing of a simple calculation: 
1.  $debug = ezcDebug::getInstance();
2.  $debug->startTimer( "Simple calculation" );
3.  
4.  // Simple calculation
5.   $result = 4 + 6;
6.  
6.  $debug->stopTimer( "Simple calculation" ); // Parameter can be omitted.
To get timing points, accumulators, use the switchTimer() method. This is shown in the next example: 
 1.  $debug = ezcDebug::getInstance();
 2.  $debug->startTimer( "My script" );
 3.  // ...
 4.   $debug->switchTimer( "Reading ini file" );
 5.  // ...
 6.   $debug->switchTimer( "Initializing template parser" );
 7.  // ...
 8.   $debug->switchTimer( "Parsing" );
 9.  // ...
10.   $debug->stopTimer();

Method Summary

public static void debugHandler( $errno, $errstr, $errfile, $errline, $erstr )
Dispatches the message and error type to the correct debug or log function.
public string generateOutput( )
Returns the formatted debug output.
public ezcLog getEventLog( )
Returns the instance of the EventLog used in this class.
public static ezcDebug getInstance( )
Returns the instance of this class.
public void log( $message, $verbosity, [$extraInfo = array()] )
Writes the debug message $message with verbosity $verbosity.
public void reset( )
Resets the log messages and timer information.
public void setOutputFormatter( $formatter )
Sets the formatter $reporter for the output.
public void startTimer( $name, [$group = null] )
Starts the timer with the identifier $name.
public void stopTimer( [$name = false] )
Stops the timer identified by $name.
public void switchTimer( $newName, [$oldName = false] )
Stores the time from the running timer, and starts a new timer.

Methods

debugHandler

void debugHandler( int $errno, $errstr, string $errfile, int $errline, int $erstr )
Dispatches the message and error type to the correct debug or log function.
This function should be used as the set_error_handler from the trigger_error function.
Use for example the following code in your application:
1.  function debugHandler( $a, $b, $c, $d )
2.  {
3.     ezcDebug::debugHandler( $a, $b, $c, $d );
4.  }
5.  
6.  set_error_handler( "debugHandler" );
Use trigger_error to log warning, error, etc:
1.  trigger_error( "[Paynet, templates] Cannot load template", E_USER_WARNING );
See the PHP documentation of trigger_error for more information.

Parameters

Name Type Description
$errno int  
$erstr int  
$errfile string  
$errline int  
$errstr  

generateOutput

string generateOutput( )
Returns the formatted debug output.

getEventLog

ezcLog getEventLog( )
Returns the instance of the EventLog used in this class.
The returned instance is not the same as retrieved via the ezcLog::getInstance() method.

getInstance

ezcDebug getInstance( )
Returns the instance of this class.
When the ezcDebug instance is created it is automatically added to the instance of ezcLog.

log

void log( string $message, int $verbosity, [ $extraInfo = array()] )
Writes the debug message $message with verbosity $verbosity.

Parameters

Name Type Description
$message string  
$verbosity int  
$extraInfo array(string=>string)  

reset

void reset( )
Resets the log messages and timer information.

setOutputFormatter

void setOutputFormatter( ezcDebugOutputFormatter $formatter )
Sets the formatter $reporter for the output.
If no formatter is set ezcDebugHtmlReporter will be used by default.

Parameters

Name Type Description
$formatter ezcDebugOutputFormatter  

startTimer

void startTimer( mixed $name, [mixed $group = null] )
Starts the timer with the identifier $name.
Optionally, a timer group can be given with the $group parameter.

stopTimer

void stopTimer( [mixed $name = false] )
Stops the timer identified by $name.
$name can be omitted if only one timer is running.

switchTimer

void switchTimer( string $newName, [string $oldName = false] )
Stores the time from the running timer, and starts a new timer.

Parameters

Name Type Description
$newName string Name of the new timer.
$oldName string The previous timer that must be stopped. Only needed when multiple timers are running.

Last updated: Thu, 31 Jan 2008