Instrumenting The Code

Instrumenting The Code.

There are four main routines that you can use to instrument your codebase.
$debug_object->debug_log($level, $variable[, $list])
$debug_object->debug_log_entry($level)
$debug_object->execute_debug($level)
$debug_object->debug_output($variable[, $list])

Bonus: $debug_object->_debug_output($variable[, $list])

NOTE: all calls take $level either as an integer or as a comma separated list of levels("2,0,-4") or as "*" which matches ALL levels.

$debug_object->debug_log($level, $variable[, $list]);
This is the most used call. Put it anywhere with variables or text that you want to see.
an example:

$debug_object->debug_log("3,-11", "after big loop, counter: ", $counter, $something, $array);

$debug_object->debug_log_entry($level);
This is a shortcut wrapper used on entry into a routine to show all of the variables that were used to call that routine.
AS an example:

global $debug_object;
$debug_object->debug_log_entry(1);

are quite often the first 2 lines of every function that I write.

$debug_object->execute_debug($level)
Gives direct access to the decision as to whether debug is turned on or not.
This call returns a boolean, so it can be placed inside of an if statement, and if debug is on then that code is executed.

if ($debug_object->execute_debug(2))
{
    // some code here that only gets executed if debug level 2 or higher is on for this routine.
    $x = 5; // Yes, REAL complex code can go here, this is just an example).
    echo "results of that code above: " . $x;
}

$debug_object->debug_output($variable[, $list])
Sometimes it's desired to have output HAVE the same format as the rest of the debug output in a log - prepended with the file and routine name for example.
This routine will do that for you, except it ALWAYS runs.
I have found it usefull in "catch" blocks for example.

Bonus: $debug_object->_debug_output($variable[, $list])
This is a very nice structured output routine that can dump any given list of variables, including arrays or object to the selected output (error_log - or echoed to the screen) I like it more than var_dump