BenchmarkIt

<?php
class benchmark {
/*
Class: benchmark
Version: 1.0
Written by: J. Thomas Enders
Last Modified: 05-03-2003
Last Modified by: J. Thomas Enders
Purpose: This class has all the functionality needed to benchmark php scripts.
The readme file has more details on instalation and use of this class.
*/
  var $startTime,$endTime,$runLength,$fileName,$error,$programName,$programVer;
  
  function benchmark($fileName = 'benchmark.txt',$programVer = '1.0',$programName) {
  /*
    Name: benchmark
    Version: 1.0
    Preconditions: None
    Postconditions: Class variables have been instantiated
    Parameters:
      $fileName - The file that logged run times will be stored in.
      $programVer - The version number of the program being bench marked
      $programName - The name of the program being bench marked
    Purpose: This function instantiates the class variables.
    Last Revision Date: 5-3-2003
    Last Revised By: J. Thomas Enders
  */

    //initialize class constants
    define('IS_ON',1); //set to 1 for benchmarking or 0 to turn benchmarking off.

    //if program name is not specified exit with failure.
    if($programName == '') {return 0;}
    
    //initialize variable class variables
    $this->programName = $programName;
    $this->programVer  = $programVer;
    $this->fileName    = $fileName;
    
    //initialize static class variables
    $this->startTime   = 0;
    $this->endTime     = 0;
    $this->runLength   = 0;
    
    return 1;
  } //end benchmark
  
  function startMark() {
  /*
    Name: startMark
    Version: 1.0
    Preconditions: class has been initialized
    Postconditions: startTime has been set
    Parameters: none
    Purpose: starts the bench mark clock
    Last Revision Date: 5-3-2003
    Last Revised By: J. Thomas Enders
  */
  
    //if benchmarking is turned off return true
    if(!IS_ON) {return 1;}
    
    //set and return start time or set error and return false.
    if($this->startTime = microtime()) {return $this->startTime;}
    else {
      $this->error = "Error: benchmark->startMark Could not initialize start time variable.<br>n";
      return 0;
    }
  } //end startMark
  
  function endMark() {
  /*
    Name: endMark
    Version: 1.0
    Preconditions: startTime has been initialized
    Postconditions: endTime has been initialized
    Parameters: none
    Purpose: Turns the bench mark clock off
    Last Revision Date: 5-3-2003
    Last Revised By: J. Thomas Enders
  */
  
    //if benchmarking is turned off return true
    if(!IS_ON) {return 1;}
    
    //if start time has not been initialized set error and return false.
    if(!$this->startTime) {
      $this->error = "Error: Start Time Not Initialized. Call startMark before endMark.<br>n";
    }
    
    //set and return end time or set error and return false
    if($this->endTime = microtime()) {return $this->endTime;}
    else {
      $this->error = "Error: benchmark->endMark Could not initialize end time variable.<br>n";
      return 0;
    }
  } //end endMark
  
  function runTime() {
  /*
    Name: runTime
    Version: 1.0
    Preconditions: startTime and endTime have been initialized
    Postconditions: runLength has been initialized
    Parameters: none
    Purpose: calculate the number of microseconds it took a program to run.
    Last Revision Date: 5-3-2003
    Last Revised By: J. Thomas Enders
  */
  
    //if benchmarking is turned off return true.
    if(!IS_ON) {return 1;}
    
    //if start time has not been initialized set error and return false.
    if(!$this->startTime) {
      $this->error = "Error: Start Time Not Initialized. Call startMark before runTime.<br>n";
      return 0;
    }
    
    //if end time has not been initialized ser error and return false.
    if(!$this->endTime) {
      $this->error = "Error: End Time Not Initialized. Call endMark before runTime.<br>n";
    }
    
    //set and return runLength
    $this->runLength = ($this->endTime) - ($this->startTime);
    return $this->runLength;
  } //end runTime
  
  function logTime() {
  /*
    Name: logTime
    Version: 1.0
    Preconditions: startTime, endTime and runLength have been initialized
    Postconditions: The benchmark has been written to the log file
    Parameters: none
    Purpose: Records the benchmark in a log file for later use
    Last Revision Date: 5-3-2003
    Last Revised By: J. Thomas Enders
  */
  
    //if benchmarking is turned off return true
    if(!IS_ON) {return 1;}
    
    //if startTime is not initialized set error and return false
    if(!$this->startTime) {
      $this->error = "Error: Start Time Not Initialized. Call startMark before logTime.<br>n";
      return 0;
    }
    
    //if endTime is not initialized ser error and return false
    if(!$this->endTime) {
      $this->error = "Error: End Time Not Initialized. Call endMark before logTime.<br>n";
      return 0;
    }
    
    //if runLength is not initialized ser error and return false
    if(!$this->runLength) {
      $this->error = "Error: Run Time Not Initialized. Call runTime before logTime.<br>n";
      return 0;
    }
    
    //if we cannot open the log file set error and return false
    if(!($outFile = fopen($this->fileName,'a'))) {
      $this->error = "Error: benchmark->logTime Could Not open (" . $this->fileName . ") log file for writting.<br>n";
      return 0;
    }
    
    //create the log entry
    $now = getdate();
    $outPut = $this->programName . " v" . $this->programVer . " ran in " . $this->runLength . " miliseconds on " . $now['month'] . " "  . $now['mday'] . ", " . $now['year'] . "n";

    //if we cannot lock the file set error and return false
    if(!flock($outFile,LOCK_EX)) {
      $this->error = "Error: benchmark->logTime Could Not Obtain an exclusive lock on (" . $this->fileName . ") log file.<br>n";
      fclose($outFile);
      return 0;
    }
    
    //log benchmark, unlock the log file, close the log file and return true
    fwrite($outFile,$outPut);
    flock($outFile,LOCK_UN);
    fclose($outFile);
    return 1;
  } //end logTime
  
  function reportTime() {
  /*
    Name: reportTime
    Version: 1.0
    Preconditions: startTime, endTime and runLength are set
    Postconditions: the benchmark has been echoed to the screen
    Parameters: none
    Purpose: echo the benchmark to the screen
    Last Revision Date: 3-5-2003
    Last Revised By: J. Thomas Enders
  */

    //if benchmarking is turned off return a null sctring
    if(!IS_ON) {return '';}
    
    //if startTime is not initialized set error and return false
    if(!$this->startTime) {
      $this->error = "Error: Start Time Not Initialized. Call startMark before reportTime.<br>n";
      return 0;
    }
    
    //if endTime is not initialized set error and return false
    if(!$this->endTime) {
      $this->error = "Error: End Time Not Initialized. Call endMark before reportTime.<br>n";
      return 0;
    }
    
    //if runLength is not initialized set error and return false
    if(!$this->runLength) {
      $this->error = "Error: Run Time Not Initialized. Call runTime before reportTime.<br>n";
      return 0;
    }
    
    
    //create the output string, echo the output string, return true
    $now = getdate();
    $outPut = $this->programName . " v" . $this->programVer . " ran in " . $this->runLength . " miliseconds on " . $now['month'] . " "  . $now['mday'] . ", " . $now['year'] . "<br>n";
    echo $outPut;
    return 1;
    
  } //end reportTime
  
  function help() {
  /*
    Name: help
    Version: 1.0
    Preconditions: none
    Postconditions: help screen echoed to the browser
    Parameters: none
    Purpose: print the help screen for the user
    Last Revision Date: 5-3-2003
    Last Revised By: J. Thomas Enders
  */
?>
<h1 align=center>BenchmarkIt v1.0 Help Screen</h1>
<h2 align=center>Installation:</h2>
To install BenchmarkIt on your website simply upload the benchmark.php file to any location on your web server.<br>

<h2 align=center>Usage:</h2>
Append this code:<br><br>

<?highlight_string('include_once('<path to benchmark.php>/benchmark.php');')?><br>
<?highlight_string('$bench = new benchmark('<full path to logs directory>/logName.extension','prgVer','program Name');')?><br>
<?highlight_string('$bench->startMark();')?><br><br>

to the very top of your php script<br><br>

For screen output append this code:<br><br>

<?highlight_string('if(!$bench->endMark()) {echo $bench->get('error');}')?><br>
<?highlight_string('if(!$bench->runTime()) {echo $bench->get('error');}')?><br>
<?highlight_string('if(!$bench->reportTime()) {echo $bench->get('error');}')?><br><br>

to the end of your script<br><br>

For log file output append this code:<br><br>

<?highlight_string('if(!$bench->endMark()) {echo $bench->get('error');}')?><br>
<?highlight_string('if(!$bench->runTime()) {echo $bench->get('error');}')?><br>
<?highlight_string('if(!$bench->logTime()) {echo $bench->get('error');}')?><br><br>

to the end of your script<br><br>

For screen and log file output append this code:<br><br>

<?highlight_string('if(!$bench->endMark()) {echo $bench->get('error');}')?><br>
<?highlight_string('if(!$bench->runTime()) {echo $bench->get('error');}')?><br>
<?highlight_string('if(!$bench->logTime()) {echo $bench->get('error');}')?><br>
<?highlight_string('if(!$bench->reportTime()) {echo $bench->get('error');}')?><br><br>

to the end of your script<br><br>

<h2 align=center>Turning BenchmarkIt on and off</h2>
There is a flag in benchmark.php that will turn benchmarking on and off. Line 30 includes this code:<br><br>

<?highlight_string('define('IS_ON',1);')?><br><br>

If you turn the 1 to a 0 then BenchmarkIt will not report any results to the screen or the log file
and all functions will return true to fool any error trapping you may have done. Except for reportTime
which returns the null string when benchmarking is turned off. This feature allows benchmarking to be
quickly and easily turned off for an entire set of scripts from a single location.<br><br>

<h2 align=center>Functions</h2>
<b>about</b> - print the about screen for the user<br>
<b>endMark</b> - turns the bench mark clock off<br>
<b>get</b> - safely retrieves a class variable for the user<br>
<blockquote>
    <b>Parameters:</b><br>
      &nbsp;&nbsp;&nbsp;&nbsp;$What - the name of the class variable to return<br>
    <b>Acceptable Values:</b><br>
       &nbsp;&nbsp;&nbsp;&nbsp;startTime, endTime, runLength, fileName, programName, pragramVer, error<br>
</blockquote>
<b>help</b> - print the help screen for the user<br>
<b>logTime</b> - records the benchmark in a log file for later use<br>
<b>reportTime</b> - echo the benchmark to the screen<br>
<b>runTime</b> - calculate the number of microseconds it took a program to run.<br>
<b>startMark</b> - starts the bench mark clock<br>
<?
  } //end help
  
  function about() {
  /*
    Name: about
    Version: 1.0
    Preconditions: none
    Postconditions: about screen echoed to the browser
    Parameters: none
    Purpose: print the about screen for the user
    Last Revision Date: 5-3-2003
    Last Revised By: J. Thomas Enders
  */
?>
<h1 align=center>BenchmarkIt  v1.0</h1>
<center>
Written By: J. Thomas Enders - Freelance Web Developer<br>
<a href=mailto:[email protected]>[email protected]</a>
</center>
<?
  } //end about
  
  function get($What) {
  /*
    Name: get
    Version: 1.0
    Preconditions: none
    Postconditions: requested class variable has been returned to the user
    Parameters:
      $What - the name of the class variable to return
    Purpose: safely retrieves a class variable for the user
    Last Revision Date: 5-3-2003
    Last Revised By: J. Thomas Enders
  */
  
    //if benchmarking is turned off return a null sctring
    if(!IS_ON) {return '';}

    //return the variable the user requested. If an invalid variable is passed then
    //set error and return false.
    switch ($What) {
      case 'startTime':
        return $this->startTime;
      case 'endTime':
        return $this->endTime;
      case 'runLength':
        return $this->runLength;
      case 'fileName':
        return $this->fileName;
      case 'programName':
        return $this->programName;
      case 'programVer':
        return $this->programVer;
      case 'error':
        return $this->error;
      default:
        $this->error = "Error: Invalid Field ($What) Passed To benchmark->Get.<br>n";
    }
    return 0;
  }
}// end benchmark