Random writings on running, software & product development, business and anything else

Introduction to PHP with Xdebug

This article is an introduction to some of the ways Xdebug can help you with your PHP code. Xdebug is a stable and mature PHP extension that can be invaluable in debugging and profiling your PHP code.

The examples here are kept deliberately simple. It is assumed you already have PHP and Xdebug installed on your system. Examples and output presented are from Ubuntu 8.10 but differences with other systems will be minor.
The current version of Xdebug is 2.0.3 and it works with PHP 4.3 to 5.3. Windows and UNIX type systems are supported. Xdebug uses the Xdebug license which is based on the PHP license.

Xdebug Configuration

On many operating systems, Xdebug configuration is in php.ini. On the Ubuntu setup with PHP 5 it is in /etc/php5/conf.d/xdebug.ini, but this will be varied to your particular needs.

xdebug.trace_format = 0
xdebug.auto_trace = Off
xdebug.trace_output_dir = /tmp/trace
xdebug.trace_output_name = xdebug.%c.%p
xdebug.collect_params = 0
xdebug.collect_includes = On
xdebug.collect_return = Off
xdebug.show_mem_delta = On

Configuration settings control when and where trace information is captured, and to what level of detail. Collecting all possible output and you can quickly end up with a very large file. These configuration settings and others are explained in detail in the official documentation. Restart your web server when you modify your Xdebug settings, and make sure the trace_output_dir is writeable by the web server user.

Xdebug trace

Lets start with some simple code with an obvious bug and see what we get:


function squareNumber($number) {
  return $number * $numbr;
<title>Xdebug test 1</title>
<tr><td>Number</td><td>Number Squared</td></tr>
  for ($i=0; $i<5; $i++) {
    echo '<tr><td>'.$i.'</td><td>'.squareNumber($i).'</td></tr>';

If you execute this code you can see a problem. The way many programmers would attack this problem is the add echo’s within the code and track down the problem. Obviously the bigger the problem, the harder this approach becomes. And who has not left debug code behind. Xdebug offers an alternative, so lets first look at some Xdebug trace output:

TRACE START [2008-12-17 02:12:39]
0.0009 59312 +308 -> squareNumber() /srv/www/xtest/test1.php:17
0.0009 59464 +152 -> squareNumber() /srv/www/xtest/test1.php:17
0.0010 59464 +0 -> squareNumber() /srv/www/xtest/test1.php:17
0.0010 59464 +0 -> squareNumber() /srv/www/xtest/test1.php:17
0.0010 59464 +0 -> squareNumber() /srv/www/xtest/test1.php:17
0.0012 26456
TRACE END [2008-12-17 02:12:39]

From this very simple example we can see useful code profiling information. The 1st column is a running execution time. Secondly is the amount of memory used. Third is the incremental amount of memory used and lastly the function call made and where from. Given the squareNumber function is called 5 times we get 1 line per call.
If we modify the Xdebug configuration slightly we can gather greater output for our debugging purposes.

xdebug.collect_params = 4
xdebug.collect_return = On

Restart the web server, rerun the example, and as can be seen below we now have details on function inputs and return values which can be helpful in script debugging. In this case our very obvious bug is there to be seen. The input is correct, but function output is always zero. Fix the code to $number * $number and we get much better results.

TRACE START [2008-12-17 02:43:32]
0.0007 59320 +308 -> squareNumber($number = 0) /srv/www/xtest/test1.php:17
>=> 0
0.0008 59472 +152 -> squareNumber($number = 1) /srv/www/xtest/test1.php:17
>=> 0
0.0009 59472 +0 -> squareNumber($number = 2) /srv/www/xtest/test1.php:17
>=> 0
0.0009 59472 +0 -> squareNumber($number = 3) /srv/www/xtest/test1.php:17
>=> 0
0.0009 59472 +0 -> squareNumber($number = 4) /srv/www/xtest/test1.php:17
>=> 0
0.0012 26464
TRACE END [2008-12-17 02:43:32]

This simple example has only scratched the surface of the power of Xdebug and how it can help your code debugging. In a safe dev environment, play around with more complex code and Xdebug config options.

For very large code move the xdebug_start_trace() function call closer to a potential problem, and close down the trace with xdebug_stop_trace(). Never leave these calls in production code, as it slows down processing.

1 Comment

  1. William Brown

    Thanks for the nice intro, but can you do a part 2 which is a bit more in depth.

© 2024 Ernie Leseberg

Theme by Anders NorenUp ↑