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).
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.
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:
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;
~~~~~