Hello World

Small or large problem, a good debugging tool is always helpful.

The most common method to debug PHP scripts is probably cluttering your code with echo statements that tell you what values your variables have. This is okay, but it's a bit tedious as you need to add the echo's to your code and remove them later. There's are also functions like var_dump for displaying detailed info about a variable, but the format it uses isn't the best possible, and the function debug_print_backtrace, but the output it gives is very cluttered and confusing.

Configuring PHP for debugging

There are some things you should always do when you are writing PHP code.

Set error reporting to E_ALL:

error_reporting(E_ALL);

If you are using PHP5, you may want to enable E_STRICT errors too:

error_reporting(E_ALL|E_STRICT);

I have heard that some E_STRICT errors in PHP5 will become fatal errors in PHP6, so it's a good way to prepare your scripts for the new version.


Enable display_errors or log_errors:

ini_set('display_errors',1);
ini_set('log_errors',1);

You should always have either display_errors or log_errors enabled.
Setting display_errors to 1 will make PHP display all errors on the page and log_errors will make it dump the errors to the server error log. If you use log_errors, it can be a good idea to set a custom error log file:

ini_set('error_log','/path/to/error.log');

Using log_errors is particularily useful if your script has redirects, which may mean that a notice or a warning which does not result in the script exiting will never be visible to you because a redirect moved you elsewhere. They will, however, be visible in the error log.

Enable ASSERT_BAIL:

assert_options(ASSERT_BAIL,1);

If you use asserts in your code, setting ASSERT_BAIL to 1 will make PHP immediately stop executing the script if an assert fails. By default, it will issue a warning which does not stop the script processing.


With these done, you should be all set. PHP will now show all the errors to you in one format or another.

PHP debug functions

PHP has some useful functions that aid in finding problems:

• var_dump
  Displays information about variables, including data type and other things
  
• debug_print_backtrace and debug_backtrace
  Displays a full backtrace including variables in the local scope. Useful, but the format can be somewhat confusing.
  
• set_error_handler
  Lets you set a custom error handler. This can be useful if you want to for example, send emails to someone when the script causes an error.
  
• set_exception_handler
  Same as set_error_handler except for exceptions.
  

I've found var_dump and debug_print_backtrace the most useful of these. However, there's still something you could do...

Install Xdebug

Xdebug is a free PHP extension that helps a lot in debugging your scripts. Here's just a few of the many useful features in it:

PHP error messages are modified to contain a stack trace, which means you will see which function caused the error, what line, which function called that function and from what line and file, etc.
This can also be configured so, that it also displays what the parameters for the function were, what local and/or global variables are defined etc.

var_dump is modified with color coding and more. This makes it much more useful as you won't need to use <pre> tags around it to get proper formatting anymore.

Memory usage, profiling, infinite loop/recursion protection etc.


I highly recommend installing this extension. Just the stack trace on PHP errors has helped me a lot in finding what's wrong in the code.

Go check out the Xdebug docs for a better list of the features.

What else?

You can also get Zend Studio, which comes with a debugger which supports step by step execution, breakpoints etc., but it's not free. Xdebug also supports some debug clients, so you can try using some of the clients listed.


I hope this helps in your efforts to make your scripts work! Remember, if your script doesn't run clear, without errors/notices/warnings/anything on E_ALL, it's not working properly.