<?php
////
// Author: Sean Colombo
// Date: 20080317
//
// This file is a tool for profiling a PHP application to find potential bottlenecks in the system.
//
// Usage:
//	At the top of a function (or chunk of code), write:
//		profiler_beginSection('function_name');
//	At the end of the function or chunk of code, write:
//		profiler_endSection('function_name');
//
// To see a report of the results of the profiling, call profiler_printResults().
//
// NOTE: The profiling will only occur if RUN_PROFILER is defined as true.
//
// DEV NOTE: When writing this code, make sure to remember to do as much as possible of the processing
// outside of when the timers are started and stopped.
//
// If a function is called recursively (called at all from inside itself), only the outside function call will be profiled.
//
// Functions:
//	profiler_beginSection()
//	profiler_endSection()
//	profiler_printResults()
////

// NON-PORTABLE: Sites which are more worried about security & secrecy of their code might want to remove the if statement and just leave the last definition.
if(isset($_GET['RUN_PROFILER']) && (($_GET['RUN_PROFILER'] == "true") || ($_GET['RUN_PROFILER'] == "false"))){
	define('RUN_PROFILER', ($_GET['RUN_PROFILER'] == "true")); // allows a url-parameter to override the default.
} else {
	define('RUN_PROFILER', false); // CHANGE THIS to turn on/off profiling!
}
if(RUN_PROFILER){
	// These variables will only be declared if they are needed.
	GLOBAL $profiler_timers,$profiler_stats,$profiler_startedAt;
	$profiler_startedAt = microtime(true);
	$profiler_timers = array(); // associative array of start-times.
	$profiler_stats = array(); // associative array of section names to an array of (total time, number of times the timer has run).
	define('PROFILER_STATS_TOTAL_TIME', 0);
	define('PROFILER_STATS_NUM_RUNS', 1);

	class Profiler_Timer{
		private $time_start;
		private $numStarts; // to make sure nested calls work as spec'ed (they only time the outermost call).
		public function Profiler_Timer(){
			$this->time_start = "";
			$this->numStarts = 0;
		}
		public function start(){
			if($this->numStarts == 0){
				$this->time_start = microtime(true);
			}
			$this->numStarts++;
		}
		public function stop(){
			$this->numStarts--;
			return microtime(true);
		}
		public function isStopped(){return ($this->numStarts == 0);}
		public function getStartTime(){return $this->time_start;}
	}
}

////
// Marks the beginning of a chunk of code for the profiler to analyze.
////
function profiler_beginSection($sectionName){
	if(RUN_PROFILER){
		GLOBAL $profiler_timers;
		if(isset($profiler_timers[$sectionName])){
			$profiler_timers[$sectionName]->start(); // doesn't change the time, just allows this nested call to be ignored.
		} else {
			$timer = new Profiler_Timer();
			$timer->start();
			$profiler_timers[$sectionName] = $timer;
		}
	}
} // end profiler_beginSection()

////
// Marks the end of a chunk of code for the profiler to analyze.
////
function profiler_endSection($sectionName){
	if(RUN_PROFILER){
		GLOBAL $profiler_timers,$profiler_stats;
		if(isset($profiler_timers[$sectionName])){
			$timer = $profiler_timers[$sectionName];
			$time_end = $timer->stop();
			if($timer->isStopped()){
				$time_start = $timer->getStartTime();
				if(! isset($profiler_stats[$sectionName])){
					$profiler_stats[$sectionName] = array(0,0);
				}
				$profiler_stats[$sectionName][PROFILER_STATS_TOTAL_TIME] += ($time_end - $time_start);
				$profiler_stats[$sectionName][PROFILER_STATS_NUM_RUNS]++;
				unset($profiler_timers[$sectionName]); // done with this timer, remove it from the group of active timers
			}
		} else {
			print "WARNING: Profiler: Trying to end a section which does not have a timer running: \"$sectionName\".";
			if(isset($profiler_stats[$sectionName])){
				print "  There are stats for this section-name, so the section may have already been ended.";
			}
			print "\n";
		}
	}
} // end profiler_endSection()

////
// Displays the results of the profiler.
// If there are any open timers, this just closes them.
//
// TODO: Either chose a logical sorting method (as-used, alphabetical, by total||average time, by number of calls) or allow
// a sorting type to be passed in or configured.  Another option would be to use jQuery sorttables.
//
// WARNING: After this function is called, if there were any timers open it will no longer be accurate to call this function
// again.  A good rule to follow is to call this function only once per page-load unless you understand what this means.
////
function profiler_printResults(){
	if(RUN_PROFILER){
		// Close all open timers.
		GLOBAL $profiler_timers,$profiler_stats,$profiler_startedAt;
		$hangingTimers = array();
		print "<pre>\n";
		while(count($profiler_timers) > 0){
			foreach($profiler_timers as $sectionName=>$timer){
				print "WARNING: Profiler: Closing hanging timer... \"$sectionName\".\n";
				$hangingTimers[] = $sectionName;
				profiler_endSection($sectionName);
			}
		}

		// Go through the stats and display the table.
		$totalTime = $totalRuns = 0;
		$precision = 5; // chosen arbitrarily... number of decimal points to display in the results
		print "<table border='1' style='font-family:courier,monospace;text-align:right;'>\n";
		print "<tr><th style='text-align:left'>Section Name </th><th> total(sec)</th><th> calls</th><th> ave(sec)</th></tr>\n";
		foreach($profiler_stats as $sectionName => $statsArray){
			$total = $statsArray[PROFILER_STATS_TOTAL_TIME];
			$numRuns = $statsArray[PROFILER_STATS_NUM_RUNS];
			$totalTime += $total;
			$totalRuns += $numRuns;
			print "<tr>";
			print "<td style='text-align:left'>$sectionName</td>";
			print "<td>".number_format($total, $precision, '.', '')."</td>";
			print "<td>$numRuns</td>";
			print "<td>".number_format(($total / $numRuns), $precision, '.', '')."</td>";
			print "</tr>\n";
		}
		print "<tr><td style='text-align:left;font-weight:bold'>Totals</td>";
		print "<td><em>".number_format($totalTime, $precision, '.', '')."</em></td>";
		print "<td><em>$totalRuns</em></td>";
		print "<td><em>".number_format(($totalTime / $totalRuns), $precision, '.', '')."</em></td>";
		print "</tr>\n";
		print "</table>\n";
		print "Total runtime (including code that wasn't profiled): ";
		print number_format(microtime(true) - $profiler_startedAt, $precision, '.', '');
		print "</pre>\n";

		// Reopen timers that were hanging so that they can be closed without throwing warnings later.
		// WARNING: These timers won't be accurate after this point (since part of the run was recorded
		// already as being a whole run, and the remainder of this run will be recorded as another separate run).
		foreach($hangingTimers as $sectionToReopen){
			profiler_beginSection($sectionToReopen);
		}
	} else {
		print "WARNING: Called ".__FUNCTION__ ." but profiling is disabled.\n";
	}
} // end profiler_printResults()

?>