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
• Monitor execution time
• Dump of all types of variable
• Send messges to js console(Chrome only),for ajax scripts

Getting Started

The class works right out of the box by calling the method debugLoader().

1. require_once('PtcDebug.php');
2. $_GET['debug']=true;        # turn on the debug
3. //$_GET['debugOff']=true;    # turn off debug
4. PtcDebug::debugLoader();

Class Options

The following example passes options to the class on load:

1. $debug_options=array
2. (
3.     'url_key'                =>    'debug',
4.     'url_pass'                =>    'true',
5.     'replace_error_handler'    =>    true,
6.     'check_referer'            =>   false,
7.     'die_on_error'            =>    true,
8.     'debug_console'        =>    false,
9.     'allowed_ips'            =>    null,
10.     'session_start'            =>    false,
11.     'show_interface'        =>    true
12. );
13. PtcDebug::debugLoader($debug_options);

url_key

To show the interface we use a "$_GET" paramater in the url, the default key is "debug" and should be changed to something else!

Default value: debug (string)

url_pass

This is the value to pass in the url, the default value is "true" and should be changed to something else.See url_key.

Default value: true (string)

replace_error_handler

Set this options to true to replace the default php error handler and php will send errors to the debug panel.It is recommended to leave it set to true.

Default value: true (bool)

check_referer

This option,if set to true,will check for the key and 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".For more information on this setup see Ajax Debugging(Chrome only)

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 replace_error_handler 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.For more information and detailed usage,see Ajax Debugging(Chrome only)

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 key and pass in $_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 "true",does not show the floating panel. It is usefull to send messages to console only. See debug_console and Ajax Debugging(Chrome only)

Default value: true (bool)

Logging Messages

To log messages is quite simple, use the bufferLog() method

Simple Message

1. $var=array("a","b","c");
2. PtcDebug::bufferLog($var);                    # send an array to the buffer
3. PtcDebug::bufferLog($var,"this is some array");    # send message with a statement

Debugging Functions

1. # Adding __FUNCTION__ is optional, but can be more precise.
2. function test_debug()
3. {
4.     // do something
5.     PtcDebug::bufferLog("function executed","",__FUNCTION__);
6. }

Debugging Classes

1. # Adding __FUNCTION__ & __CLASS__ is optional, but can be more precise.
2. class testDummy()
3. {
4.     public function foo()
5.     {
6.         // do something
7.         PtcDebug::bufferLog("method executed","",__FUNCTION__,__CLASS__);
8.     }
9. }

Logging Sql Queries

To log sql queries is just like logging messages, but this time we will be using the bufferSql() method

1. $sql="SELECT * FROM some_table";
2. PtcDebug::bufferSql($sql);            # send a sql query to buffer
3. $result=mysql_query($sql);
4. PtcDebug::stopTimer();                # show execution time for this query

Execution Timing

To check how long things take to execute you can use the stopTimer() method.

Sql Query

1. $sql="SELECT * FROM some_table";
2. PtcDebug::bufferSql($sql);            # send a sql query to buffer
3. $result=mysql_query($sql);
4. PtcDebug::stopTimer();                # show execution time for this query

Loops

1. PtcDebug::bufferLog("Loop execution time");    # send a message to the buffer
2. for($i=0;$i<5000;$i++)
3. {
4.     //do something
5. }
6. PtcDebug::stopTimer();    # chain execution time to previous message

Script execution(in seconds)

1. PtcDebug::bufferLog("script execution time");    # send a message to the buffer
2. //do something
3. # chain execution time to previous message, param 0 is to use seconds
4. PtcDebug::stopTimer(0);

Replace 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,the parameter should be left set to "true"(see die_on_error).

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

Typical Setup Examples

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::debugLoader($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),
10.     'show_interface'        =>    true
11. );
12. PtcDebug::debugLoader($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,
5.     'die_on_error'            =>    false,
6.     'debug_console'        =>    true,
7.     'check_referer'            =>    true,    # check if referer has key and pass.
8.     'show_interface'        =>    false        # don't show interface, only console
9. );
10. PtcDebug::debugLoader($debug_options);