Path

ez components / documentation / api reference / 2008.2.1 / debug


eZ Components 2008.2.1

Debug: ezcDebug

[ Tutorial ] [ Example stylesheet ] [ 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");
3.  // ...
4.   $debug->log"Connection failed, retrying in 5 seconds");
5.  // ...
6.   $debug->log"Could not connect with the server");
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 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();

Properties

ezcDebugOptions read/write  $options
Options to configure the behaviour of ezcDebug, including stack trace behaviours.

Member Variables

protected array(string=>mixed) $properties = array()
Properties.

Method Summary

public static void debugHandler( $errno, $errstr, $errfile, $errline )
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()], [$stackTrace = false] )
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, string $errstr, string $errfile, int $errline )
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  
$errstr string  
$errfile string  
$errline int  

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()], [bool $stackTrace = false] )
Writes the debug message $message with verbosity $verbosity.
Arbitrary $extraInfo can be submitted. If $stackTrace is set to true, a stack trace will be stored at the current program position.

Parameters

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

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( string $name, [string $group = null] )
Starts the timer with the identifier $name.
Optionally, a timer group can be given with the $group parameter.

Parameters

Name Type Description
$name string  
$group string  

stopTimer

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

Parameters

Name Type Description
$name string|bool  

switchTimer

void switchTimer( string $newName, [string|bool $oldName = false] )
Stores the time from the running timer, and starts a new timer.
Stores the time for $oldTimer (maybe omitted if only 1 timer is running) and starts a new timer with $newName.

Parameters

Name Type Description
$newName string  
$oldName string|bool  

Last updated: Mon, 09 Feb 2009