Class script_timer


Script timing class

Records the time it takes various parts of your script to run and displays the results in a table so you can easily analyse which parts of your script may need optimization.

With script timing you will always have some overhead for the taking of the measurements and processing thereof.
This class minimizes that overhead by excluding virtually all processing within this class from your timing calculations.


  • Add markers recorded before class instantiation
  • Temporarily pause the timer
  • Group markers by script
  • Optionally add subtotals per script (group)
  • Uses bcmath functions whenever possible for better calculation precision
  • Adjustable precision for the calculations
  • Adjustable precision for the output
  • Provides the following measurements:
    * run time for the marker (excluding processing by this class)
    * run time for the marker as a percentage of the total run time
    * cumulative run time up to the marker
    * cumulative percentage
  • Choose how you want to receive the results:
    * a two-dimentional array so you can process the results yourself
    * a html string which you can assign to whichever templating system you use
    * output straight to screen as a table
  • HTML output can easily be adjusted to your liking as the html used is contained in a template
    * the html can be adjusted in the template file (./templates/script_timing.tpl)
    * both the table as well as the rows are tagged with class names, through the use of CSS you can easily change the appearance of the table (as done in the example file)
Basics on how to use the class

Include and instantiate the class :

  1. include_once( '' );
  2. $timer = new script_timer();

Start the timer :

  1. $timer->start_timer();

Set a marker :

  1. $timer->set_marker( 'task x done' );

Optionally add a script (group) name to group a set of tasks together :

  1. $timer->set_marker( 'task y done', 'sub script y' );

Optionally pause the script after a marker:

  1. $timer->set_marker( 'task z done', 'script z', true );
... Do something you don't want timed ...
Unpause the timer when you want to start timing again
  1. $timer->unpause();

Retrieve the results :

Method 1a - as a two-dimentional array without subtotals:

  1. $timer->end_timer( false );
  2. $timer_array = $timer->scripttiming;

Method 1b - as a two-dimentional array with subtotals and custom marker name for the end marker:

  1. $timer->end_timer( true, 'My end marker name', 'My script name' );
  2. $timer_array = $timer->scripttiming;

Method 2 - as a html string : (example uses a precision of 6 digits and ISO-8859-1 encoding for the html string):

  1. $html = $timer->get_output( false, 6, 'ISO-8859-1' );

Method 3 - output to screen : (example uses a precision of 4 digits and the default (utf-8) encoding for the html string):

  1. $timer->get_output( true, 4 );

Oftentimes you may want to start timing a script before you include any files / classes.
This class lets you do so and this is how:

At the start of your script, record a start time:

  1. $start = microtime();

Store any markers you want in an array:

  1. $time_array[] = array( microtime(), 'Start up task x done', 'optional script name' );

Once you have included and instantiated the class, pass these markers and your start time to the class object:

  1. $timer->add_markers( $time_array, $start );
Do not call the start_timer() method after this as add_markers() will start your timer at the first recorded time or at the start time if you pass one.

After adding your manually recorded markers, you can use the class like above to set additional markers and get the results.

After using the timer, you may want to clean up, for instance if you want to time several scripts seperately :

  1. $timer->reset();

Version management information

  • v1.0 First public release

Located in / (line 140)

Variable Summary
Method Summary
script_timer script_timer ([int $calc_precision = null], [bool $auto_start = false])
void add_markers (array $marker_array, [string $start_time = null], [bool $add_marker_for_interim = true], [string $marker_name = null], [string $script_name = null])
void end_timer ([bool $add_subtotals = false], [string $marker_name = null], [string $script_name = null])
string|bool get_output ([bool $display = false], [int $precision = null], [string $encoding = null], [bool $add_subtotals = null], [string $marker_name = null], [string $script_name = null])
void reset ()
void set_marker (string $marker_name, [string $script_name = null], [bool $pause_timer = false])
void start_timer ()
void unpause ()
int $calc_precision = 10 (line 164)

Precision for the bcmath functions and floats

Can be set through the class instantiation method

array $lang_strings = array(
'subtotal' => 'Subtotal of :', // used in end_timer()
'end_timer' => 'End of script timing', // used in end_timer()
'interim_marker' => 'Processing between setting of last manual marker and calling add_markers method' // used in add_markers()
(line 319)

Language strings used by the class

Only contains language strings which *may* be used in the output. Except for subtotal, they can be overruled by setting optional parameters when calling the related methods.

The only other language strings in this class are error messages and those are hard coded in English for obvious reasons.

string $output_encoding = 'utf-8' (line 188)

Default character encoding for output of results

Can be overruled by setting the $encoding parameter in the get_output() method

int $output_precision = 4 (line 177)

Default precision for output of results

Can be overruled by setting the $precision parameter in the get_output() method

array $scripttiming = array() (line 272)

Result array for script timing

The result array will (eventually) contain a two-dimentional array of information. Each record will hold the following information:

[#] => array(
 	[microtime_end]		=> string	microtime end time for marker
 	[microtime_elapsed]	=> string|float	microtime between start and end
 						for this marker
 	[microtime_start]	=> string	microtime start time for timing
 						of this marker
 	[marker_name]		=> string	marker name
 	[script_name] 		=> string|null	[optional] script name
 	[perc_elapsed]		=> string|float	percentage of this script part
 						compared to the whole script
 	[subtotal]		=> string|float	microtime since beginning of timing
 	[cum_perc]		=> string|float	cumulative percentage script run since
 						beginning of timing

Whether calculated figures are stored as a string or float depends on whether the bcmath extension is loaded.

bool $subtotals_added (line 302)

Variable which contains the setting used for $add_subtotals in the end_timer() method.

bool $timer_paused = false (line 281)

Variable to keep track of whether the timer is in pause mode or not

string|float $timer_total = 0 (line 245)

Sum of the timings taken (so far)

Whether this is a string or float depends on whether the bcmath extension is loaded.

Constructor script_timer (line 354)

Class instantiation

  • Checks for the bcmath extension and throws a warning if not found
  • Fetches the directory this script resides in for later use
  • [Optionally] Sets the calculation precision for the timer class.
    If the $calc_precision parameter is not set, the default setting will be used.
  • [Optionally] Starts the timer
    Do not use this feature in combination with the add_markers() method (which will start the timer automatically) !
    You can also manually start the timer at a later timer with start_timer()

script_timer script_timer ([int $calc_precision = null], [bool $auto_start = false])
  • int $calc_precision: [optional]
  • bool $auto_start: [optional] whether or not to start the timer at instantiation Defaults to false.
add_markers (line 477)

Add breakpoint microtime markers which were recorded outside of this class

Typical use: when you start your script, you first validate and normalize some data before including any classes. If you want to also time this first part of the script (i.e. before this class was instantiated), you will need to record some breakpoints yourself.

Record those breakpoints like this:

  1. $marker_array[] = array( microtime(), 'marker name', 'optional script name' );

Using this method, you can then later (once the class is instantiated) add those recorded times to the class object.

If you use this method, call this (straight) after you instantiate the class and before recording additional markers using the set_marker() method.

This method will start the timer automatically. Do not call the start_timer() method.

This method will (optionally) auto-add an extra marker for the script part between the last marker passed and the call to this method. You can optionally set your own $marker_name (and - again optionally - $script_name) for this extra marker.
If you choose not to add the extra marker, the timing for the next marker will be corrected for the processing time taken by this method call.

void add_markers (array $marker_array, [string $start_time = null], [bool $add_marker_for_interim = true], [string $marker_name = null], [string $script_name = null])
  • array $marker_array: multi-dimentional array using the following structure
    1. array(
    2. [0] => array(
    3. [0] => string recorded microtime
    4. [1] => string breakpoint marker name
    5. [2] => string [optional] script name
    6. ),
    7. [1] => array( ....),
    8. .....
    9. );
  • string $start_time: [optional] recorded microtime for start of script timing If not passed, the microtime of the first record in the array will be used as start time and the first record will have an elapsed time of 0.
  • bool $add_marker_for_interim: [optional] whether or not to add a marker for the time passed between the last marker in the array and the call to this method. Defaults to true.
    If set to false, the next marker will measure the time between the last marker and itself including the call to this method, though largely - but not completely - corrected for the time this method takes to run.
  • string $marker_name: [optional] name for the (optional) interim marker, default to the markername in $lang_strings['interim_marker']
  • string $script_name: [optional] name for the script / group for the (optional) interim marker, defaults to null (i.e. no script / group name)
end_timer (line 679)

End timer and add additional measurements to the result array

If the timer is not currently in pause mode, an end marker will be added. You can optionally specify a marker name (and - again optionally - script name) for the end marker.

Measurements added are:

  • Run time for the marker
  • Percentage of current marker compared to complete script
  • Run time of script up to the marker
  • Cumulative percentage of run time up to the marker compared to the complete script
Additionally (and optionally) subtotals can be added for groups of markers, so indicated when they where set by script name.

If you want to display / retrieve as html string the results of your timer as soon as you end the timer, you can use the get_output() method which will end the timer automatically.

void end_timer ([bool $add_subtotals = false], [string $marker_name = null], [string $script_name = null])
  • bool $add_subtotals: [optional] whether or not to add subtotals for groups of markers by script name. Defaults to false.
  • string $marker_name: [optional] marker name for the 'script timing ended' marker, default to the markername in $lang_strings['end_timer'].
  • string $script_name: [optional] script name for this last marker, defaults to null
get_output (line 799)

Retrieve the timer output either as a html string or directly printed to screen

Please refer to end_timer() for information on how (and why) to set the optional $add_subtotals, $marker_name and $script_name parameters

string|bool get_output ([bool $display = false], [int $precision = null], [string $encoding = null], [bool $add_subtotals = null], [string $marker_name = null], [string $script_name = null])
  • bool $display: [optional] whether to return the output to the screen or as a string
    false returns a html string
    true prints the results to screen
    Defaults to false.
  • int $precision: [optional] output precision of microtime values
    Defaults to $output_precision
  • string $encoding: [optional] character encoding for the html output
    Defaults to $output_encoding
  • bool $add_subtotals: [optional] only used if the timer was not previously stopped
  • string $marker_name: [optional] only used if the timer was not previously stopped
  • string $script_name: [optional] only used if the timer was not previously stopped
reset (line 871)

Reset all result variables

void reset ()
set_marker (line 577)

Record the time for a breakpoint in your script

Sets the marker for the breakpoint called $marker_name

If you use/include a lot of scripts in your page, you may want to set the optional parameter $script_name to record in which script the breakpoint resides.
Obviously you can also use $script_name to group sequential related parts of your script.
If you use the $script_name variable, you can then receive subtotals per script (group) in your timer results.

void set_marker (string $marker_name, [string $script_name = null], [bool $pause_timer = false])
  • string $marker_name: name for your breakpoint so you recognize it later
  • string $script_name: [optional] name of the current script or group
  • bool $pause_timer: [optional] pause the timer after setting this marker Defaults to false, i.e. don't pause the timer.
start_timer (line 398)

Start script timing

This is optional.
Alternatively the first time you call the set_marker() method, script timing will automatically be started.
Take note: Starting the timing via the set_marker() method will cause the timing for the first marker to be 0.

If you use the add_markers() method to add markers recorded before class instantiation, the start time will be set through that method. You should not use this method if you use add_markers().

Starting the timer - independently of which method you use - will destroy all previously recorded markers as a new timer is presumed.

void start_timer ()
unpause (line 625)

Unpause the timer

void unpause ()

Documentation generated on Fri, 08 Sep 2006 23:04:36 +0200 by phpDocumentor 1.3.0RC3