Turning It On

Turning On the $debug_object

The granularity of output from the $debug_object can be controlled in two ways, You can select what routines in your code you want debug on for (debug scope), and then you can select what level of output you want for each (debug Level).

Debug Level:

When you turn on debug code for a specific scope, you can specify what level it is to be on at.

Levels are integers, or a string comprised of a comma separated list of integers. (or a *).
Non-negative levels include all "lower" levels of debug. (So, for example, turning on the debugObjust for level 4 would also turn it on for level 3, level 2 and level 1.)
0, and negative levels turn on ONLY the code at that level, and several conventions have been created.
A * will ALWAYS match no matter what level is turned on for the scope.

Clearly you may choose what levels to use for what debugging code, but I have found the following conventions to be helpful.

• Level 1 is used for entry and exits for a routine, and showing the values that it is called with, and the values that it returns.
• Level 2 is for showing values at major code marks
• Level 3 is used for showing values inside of loops
• Level 4 is often used for when huge sql datasets are returned and you almost never really want to see them.
• Level 0 is used to turn on debug output that goes to the screen.
• Level -1 is used for timing related output.
  • A Debug timer is included with the debug_object, and is documented here: [Debug Timer]
• Level -2 is used to generate memory related output.

As you can see, any number of constructs can be created based on your codebase. I have used other negative levels when I want a specific topic no matter where it is in the codebase. For example:

• -10 can be anytime you wish to see something about the user change
• -15 can be any time you wish to see information about a clients address

Debug Scope:

The $debug_object allows you to turn on debugging for a single routine, multiple routines, all routines in a given class, all code in a given file, all the code in a given namespace or all the code in a given directory of your code hierarchy. Examples will be given below.

Specifying scope:
The debug_object contains a public array $debug. Every element in that array specifies a scope and level for that scope. If code in that scope is executed, then the level is looked at, and if there is a level match, then output is generated.

The array key specifies the scope, and the value specifies the level.
Since this is an array, you may specify as many scopes and levels as you like. However, note that since it's an associative array, you will need to specify all levels for a given scope in that one entry.

Typically, the best place to turn the object on and off is at the end of the debug_object.php file itself. This way, if you see it in your checkin list, you will know that it shouldn't get checked in, and you will never leave debug code turned on in your production codebase.

The best way to explain this is to look at a list of examples:

To turn on debug for a specific routine: (I find 3 to be a good level to use when I care about a specific routine.)

$debug_object->debug['routine_you_want'] = 3;

To turn on debug for everything inside of a specific file:

$debug_object->debug['file_you_want.php'] = 1;

To turn on debug for a specific routine inside of a specific class that is part of a specific namespace:

$debug_object->debug['namespace_you_want\\class_you_want::routine_you_want'] = 1;

To turn on debug for a specific routine INSIDE of a specific class:

$debug_object->debug['class_you_want::routine_you_want'] = 3;

To turn on debug for ALL routine INSIDE of a specific class use :: as a class specifier

$debug_object->debug['class_you_want::'] = 1;

To turn on debugging for all routines inside of a given namespace use the \ after the namespace.
(Due to PHP \ rules you will need to double it.)

$debug_object->debug['namespace_you_want\\'] = 1;

To turn on debugging for all files inside of a specific directory, use a / after the directory name.

$debug_object->debug['directory_you_want/'] = 1;

To turn on debugging inside of a specific file inside of a specific directory:

    $debug_object->debug['directory_you_want/file_you_want.php'] = 1;

or:

    $debug_object->debug['directory_you_want_a/directory_you_want_b/file_you_want.php'] = 1;

Turn on all screen output related debug output.

$debug_object->debug['DEBUG'] = 0;

Turn on all timing related debug output.

$debug_object->debug['DEBUG'] = -1;
~~~~~~
Turn on all memory related debug output.

:::text
$debug_object->debug['DEBUG'] = -2;

The next line will turn on ALL debugging.  If you have a lot debug code, be aware this can be overwhelming. (Sucker!)

:::text
$debug_object->debug['DEBUG'] = 3;
~~~~~