INTRODUCTION

The goal of this class is to ease the process of debugging php scripts. The class uses a floating panel at the top right of the page. There are also a couple of features that can fix security issues with the php default error handler. All class properties and methods are static because it's required to let them work on script shutdown when FATAL error occurs.

Main Features:

• Show globals vars ($GLOBALS, $_POST, $_GET, $_COOKIE ...)
• Show php version and loaded extensions
• Replace php built in error handler
• Log sql queries
• Catch exceptions
• Inspect variables for changes
• File inspector to view source code
• Monitor execution time
• Dump of all types of variable
• Send messages to js console for ajax scripts (Chrome only)

GETTING STARTED

The class works right out of the box by calling the method PtcDebug::load().

1. require_once('PtcDebug.php');    // include the PtcDebug class
2.     $_GET['debug']=true;               // turn on the debug
3.     PtcDebug::load();                // initialize the class

CLASS OPTIONS

This is the full list of options available on intialization, stored in PtcDebug::$_defaultOptions property:

1. $options=array                // add some options before class initialization
2.     (
3.         'url_key'                =>    'debug',    // the key to pass to the url to turn on debug
4.         'url_pass'                =>    'true',    // the pass to turn on debug
5.         'replace_error_handler'    =>    true,    // replace default php error handler
6.         'error_reporting'        =>   E_ALL,    // error reporting flag
7.         'catch_exceptions'        =>    true,    // sets exception handler to be this class method
8.         'check_referer'            =>   false,    // check referer for key and pass(good for ajax debugging)
9.         'die_on_error'            =>    true,    // die if fatal error occurs(with this class error handler)
10.         'debug_console'        =>    false,    // only for Chrome,show messages in console(phpConsole needed)
11.         'allowed_ips'            =>    null,        // restrict access with ip's
12.         'session_start'            =>    false,    // start session for persistent debugging
13.         'show_interface'        =>    true,    // show the interface(false to debug in console only)
14.         'enable_inspector'        =>    true,    // enable variables inspector, use declare(ticks=n); in code block
15.         'declare_ticks'            =>   false,    // declare ticks globally with value of 1
16.         'set_time_limit'            =>    null,        // set php execution time limit
17.         'memory_limit'            =>    null,        // set php memory size    
18.         'show_messages'        =>    true,    // show messages panel
19.         'show_globals'            =>    true,    // show global variables in vars panel
20.         'show_sql'            =>    true,    // show sql panel
21.         'trace_depth'            =>    10,        // maximum depth for the backtrace
22.         'max_dump_depth'        =>    6,        // maximum depth for the dump function        
23.         'default_category'        =>    'General'
24.     );
25.  
26.     PtcDebug::load($options);        // initialize the class

url_key

To show the interface we use a "$_GET" parameter in the url (see url_pass), and to turn it off the same parameter + "_off" is used. The default key is "debug" and should be changed to something else!

Default value: debug (string)

url_pass

The value to pass in the url (see url_key), the default value is "true" and should be changed to something else!

Default value: true (string)

replace_error_handler

Replaces the default php error handler to show php errors in the debug messages panel.

Default value: true (bool)

check_referer

This option, if set to "true", will check for the "url_key" and "url_pass" with the referer if any. This is quite usefull to debug ajax scripts with the "show_interface" option set to "false", and the debug_console set to "true".

See Ajax debugging (chrome only) for more information on this setup.

Default value: false (bool)

die_on_error

Set this option to false to continue if fatal error occurs, keep in mind that this will only work with the "replace_error_handler" option set to "true".

Default value: true (bool)

debug_console

Only for Chrome,with phpConsole class installed.This feature is usefull to to debug ajax scripts.

See Ajax debugging (chrome only) for more information and detailed usage.

Default value: false (bool)

allowed_ips

To restrict access use this option to pass an ip or an array of ip's, and only the allowed ip's will be able to turn on/off the debug interface. It is advised to use this option under production environment.

Default value: null (string|array)

session_start

For persistent debugging, set this option to true, and the class will try to store the "url_key" and "url_pass" in a "$_SESSION" var. You will need to use "url_key"+_off to hide the interface. While this is a good option to navigate an application, it will not work if the class is not initialized at very start of the application. see session_start() function for more information.

Default value: false (bool)

show_interface

This option, if set to "false", does not show the floating panel. It is usefull to send messages to console only with the option "debug_console" set to "true".

See Ajax debugging (chrome only) for more details over this setup.

Default value: true (bool)

enable_inspector

This option, enables the variable inspector, which can be used to watch if a given variable has changed. Remember to declare ticks in a code block or use the option "declare_ticks".

See INSPECTING VARIABLE CHANGES for examples.

Default value: true (bool)

declare_ticks

If the option "enable_inspector" is set to "true", this option can be used to declare ticks globally. Keep in mind that it is adviced to declare ticks inside a code block, as the backtrace might not be as precise.

See INSPECTING VARIABLE CHANGES for example usage.

Default value: false (bool)

set_time_limit

Sets the php global execution time limit.

Default value: null (float)

memory_limit

Sets memory limit for php.

Default value: null (float)

show_messages

Controls if the messages panel will be shown, if set to "false" the interface will not show this panel and will be faster to load.

This option can be turned on and off with the "$_GET" parameter "hidepanels" in the url, see HIDING PANELS for more information about this option.

Default value: true (bool)

show_globals

Controls if the "$GLOBALS" variable will be shown in the vars panel, if set to "false" the interface will not show the "$GLOBALS" and will be faster to load.

This option can be turned on and off with the "$_GET" parameter "hidepanels" in the url, see HIDING PANELS for more information about this option.

Default value: true (bool)

show_sql

This option, controls if the sql panel will be shown in the sql panel, if set to "false" the interface will not show this panel and will be faster to load.

This option can be turned on and off with the "$_GET" parameter "hidepanels" in the url, see HIDING PANELS for more information about this option.

Default value: true (bool)

trace_depth

This option sets a depth limit for the backtrace. Increase it if you think that the backtrace is leaving out files.

Default value: 10 (float)

max_dump_depth

This option sets the maximum depth when dumping variables to prevent recursion. If maximum depth is reached, the message "**MAX DEPTH REACHED** " will be shown. Increase it if you need a higher depth.

Default value: 6 (float)

default_category

The default category for the log/sql messages.

Default value: General (string)

LOGGING DATA

The following sections will explain how the messages and sql panel work.

Logging messages

To send data to the messages panel is quite simple, just use the log_msg() function.

1. /* LOGGING A MESSAGE */
2.     log_msg('just a message');
3.     
4.     /* LOGGING A VARIABLE WITH A STATEMENT */
5.     $var='something';
6.     log_msg($var,'testing a variable');
7.     
8.     /* LOGGING AN ARRAY TO THE MESSAGE PANEL WITH A DIFFERENT CATEGORY */
9.     $array=array('key'=>'value','key1'=>'value1');
10.     log_msg($array,'testing an array','new category');

Logging sql queries

To log sql queries use the log_sql() function:

1. /* LOGGING SQL QUERIES */
2.     $sql='select from where something';    // some sql query, will be used as reference
3.     log_sql('',$sql);            // leaving the first parameter empty, can be added later with the query result

EXECUTION TIMING

The class allows to time execution for php code and sql queries. The following sections will give examples on how this can be done.

Timing php code

To check how long things take to execute you can use the stop_timer() function:

1. /* TIMING A LOOP */
2.     log_msg('','timing a loop');    // leaving the first parameter empty
3.     for($i=0;$i<100;$i++){ @$a[]=$i; }
4.     stop_timer('timing a loop');    // using the reference to attach the execution time to the buffer

1. /* ATTACHING THE RESULT OF THE LOOP TO THE MESSAGE */
2.     add_to_log('timing a loop',$a);

Timing sql queries

To check how long a query takes to execute you can use the stop_timer() function.

1. /* LOGGING SQL QUERIES */
2.     $sql='select from where something';    // some sql query, will be used as reference
3.     log_sql('',$sql);            // leaving the first parameter empty, can be added later with the query result

1. $sql_result=array('key'=>'value','key1'=>'value1');    // this should be the sql result of the sql query
2.     /* TIMING THE QUERY */
3.     stop_timer($sql);                    // stop timer, the query is used as reference

1. /* ATTACHING THE QUERY RESULT TO THE MESSAGE */
2.     add_to_log($sql,$sql_result);            // attaching the result to the message based on the reference

REPLACING ERROR HANDLER

The method setErrorHandler() is used to force the replacement of the built in php error handler even if the debug panel is not shown (see replace_error_handler). This is usefull for production environment, for the simple reason that if an error occurs the user will not see information about the error. This method could also be used with the parameter set to "false", so that if fatal error occurs, script execution will still continue. Keep in mind that if you expect the script to die on error, this parameter should be left set to "true" (see die_on_error).

1. // replace php built in error handler
2.     PtcDebug::setErrorHandler();
3.     // replace php built in error handler and continue execution if fatal error occurs
4.     PtcDebug::setErrorHandler(false);

INSPECTING VARIABLE CHANGES

To check if a given variable has changed, the function watch_var() with the option "enable_inspector" set to "true" can be used:

1. /* WATCHING A VARIABLE */
2.     declare(ticks=1)
3.     {
4.         $var='some test';
5.         watch_var('var');                    // passing the variable without the "$" symbol
6.         $var='some new value';                // the variable changed
7.     }

INSPECTING SOURCE CODE

The file inspector can be used to inspect source code. This option is automatically available if session_start() is used, the file names in the panels will have an anchor that will open a popup window with the content of the file and the highlighted line of code if any.

ADDING DATA TO THE LOG

Data can be attached to a message after log_msg() and log_sql() functions are called, with the add_to_log() function. This is quite usefull if you are timing the execution of some code or a database query. The parameter "$reference" is the equivalent of the "$statement" parameter for the log_msg() or log_sql() functions which should be called before add_to_log().

See EXECUTION TIMING for practical examples.

HIDING PANELS

To load the interface faster, panels that are not required can be hidden. This can be done either by using the options available on initialization (see "show_messages","show_globals","show_sql") or by sending the "$_GET" parameter "hidepanels" in the url:

These are all the possibile options for the "hidepanels" parameter:

1. sql
2. globals
3. msg
4. all (uses all options above)
5. none (shows all panels)

TYPICAL SETUP EXAMPLES

The following sections will demonstrate 3 different setup examples depending on the circumstances.

Setup for development

This example,demostrates how to configure and load the interface under testing environment:

1. require_once('PtcDebug.php');
2. $_GET['debug']=true;        // turn on the debug
3. //$_GET['debugOff']=true;    // turn off debug
4. $debug_options=array
5. (
6.     'session_start'            =>    true,
7. );
8. PtcDebug::load($debug_options);

Production environment

This example,demostrates how to configure and load the interface under production environment:

1. require_once('PtcDebug.php');
2. // replace php built in error handler and continue execution if fatal error occurs
3. PtcDebug::setErrorHandler(false);
4. $debug_options=array
5. (
6.     'url_key'                =>    'someKey',
7.     'url_pass'                =>    'somePass',            // use a complicated string!
8.     'replace_error_handler'    =>    false,                // has been replaced already
9.     'allowed_ips'            =>    array(1.2.3.4,2.3.4.5),    // array of ip's
10.     'show_interface'        =>    true
11. );
12. PtcDebug::load($debug_options);

Ajax debugging (chrome only)

This example,demostrates how to configure and show the buffer messages in the Chrome browser console. Particularly usefull to debug ajax scripts. Keep in mind that this setup needs phpConsole class and the Chorome extension installed to work. Make sure you have downloaded the phpConsole class from the repository, and install the Chrome browser extension before starting to use this class to send messages to the console.

1. require_once('PtcDebug.php');
2. $debug_options=array
3. (
4.     'replace_error_handler'    =>    true,    // replace error handler
5.     'die_on_error'            =>    false,    // continue if fatal error
6.     'debug_console'        =>    true,    // send buffer to js console
7.     'check_referer'            =>    true,    // check if referer has key and pass.
8.     'show_interface'        =>    false        // don't show interface, only console
9. );
10. PtcDebug::load($debug_options);