Debugging PHP Applications with Xdebug and Eclipse PDT

OK, so I have x64 Eclipse successfully installed and running with all the plugins I use for Web Application Development. But what about debugging? Sure, var_dump(), echo, print and so on are all valuable to me when debugging a script, but it’s always good to have more information.

Xdebug is a fantastic PHP extension, which is written by one of the PHP Core Developers, Derick Rethans. The current version is 2.0.3, and I set about installing it on my system, and integrating it into Eclipse PDT today.

Xdebug can be installed in a few different ways – by downloading the binaries from the site, compiling the source, or via PECL:

sudo pecl install xdebug

Some days, I just prefer to download compile the source, as it gives me more of an understanding of what is being installed and where, and this is one of those days:

cd ~/
mkdir xdebug
cd xdebug
wget http://www.xdebug.org/link.php?url=xdebug203
tar -zxvf xdebug-2.0.3.tgz
cd xdebug-2.0.3

The packages phpize and php-config are required to install Xdebug, and can be obtained by installing the relevant PHP development packages:

sudo apt-get install php4-dev

or

sudo apt-get install php5-dev

depending on the PHP version installed. After unzipping the Xdebug source, I ran

phpize

which output:

PHP Api Version: 20041225
Zend Module Api No: 20060613
Zend Extension Api No: 220060519

I then checked this against the table at http://www.xdebug.org/docs/install#phpize to see if my PHP version (5.2.3) was compatible with Xdebug – it matched up to the table’s 5.2.x PHP version row, so I went ahead and installed:

./configure --enable-xdebug --with-php-config=/usr/bin/php-config
make

which created a file xdebug.so in the modules subdirectory. This file needs to be copied (or moved) to the PHP Extension directory, which on my system is in /usr/lib/php5/20060613/. An easy way to find the PHP extension directory is to run:

locate mysql.so

ok, so I copied the xdebug.so to the extension directory:

sudo cp modules/xdebug.so /usr/lib/php5/20060613/

So far so good. Now PHP needs to be told about the extension, and to load it. This can be done by adding

zend_extension="/usr/lib/php5/20060613/xdebug.so"

to the php.ini file. However, on my Ubuntu system, the PHP extensions are activated by adding an .ini file to the /etc/php5/apache2/conf.d directory, for each extension installed. The .ini file is the extension_name.ini, so I created a file called xdebug.ini:

cd /etc/php5/apache2/conf.d
gksu gedit xdebug.ini

which for now, contains a single line:

zend_extension="/usr/lib/php5/20060613/xdebug.so"

After restarting the Apache server

sudo /etc/init.d/apache2 restart

I created a file called test.php in my Web Root directory, containing a call to the phpinfo() function:

<?php
phpinfo();
?>

and pointed my browser to http://localhost/test.php. Just before the “PHP Credits” section, is a small box containing information on Zend – and now, with a successful Xdebug installation, additional information on Xdebug:

The same information can be found by opening a Terminal and running

php -m

to output the loaded modules, and towards the end of the output, you should see

[Zend Modules]
Xdebug

alternatively, run

php -i | grep Xdebug

and if Xdebug has been installed successfully, you should see

with Xdebug v2.0.3, Copyright (c) 2002-2007, by Derick Rethans

Now, Xdebug needs to be enabled before any scripts can be debugged! So, in the php.ini file (or in my case, the newly created /etc/php5/apache2/conf.d/xdebug.ini file) I added the lines:

xdebug.remote_enable=On
xdebug.remote_host="localhost"
xdebug.remote_port=9000
xdebug.remote_handler="dbgp"

and restarted Apache again:

sudo /etc/init.d/apache2 restart

running

php -i | grep xdebug

in the Terminal, or using the test.php file containing phpinfo() shows that the new settings are being used, and Xdebug is active and running.

Configuring Eclipse PDT:

Setting up Eclipse PDT to use the Xdebug extension is pretty simple. In Eclipse PDT, I opened Window -> Preferences, then clicked on PHP, expanded the tree, and selected Debug. I Chose Xdebug from the pull down menu for the PHP Debugger, the “Default PHP Server” (should already be set to localhost), and then created a new PHP Executable option by clicking on the PHP Executables link next to the PHP Executable pull down menu.

In the PHP Executables dialog, I Clicked Add, filled in the name (PHP with XDebug), and entered the path to the PHP executable – on my system this is /usr/bin/php but if you don’t know, then in a terminal, run

which php

to find out where the php command is run from. I also entered the location of php.ini – again, on my system, this is /etc/php5/apache2/php.ini – and selected XDebug as the PHP debugger:

Clicked OK, then went back to the PHP -> Debug preferences screen, and selected the PHP Executable just created in the PHP Executable pull down. Finally, in the Debug -> Workbench Options option in the left, I selected “Never” for the “allow multiple debug sessions” option, since Xdebug does not support them.

Finally, I needed to set the Default Web Browser in Eclipse, to that when I debug a script, the output is sent to Firefox. Again in Preferences, I navigated to General -> Web Browser, and clicked “New”. It’s pretty straight forward stuff – entering a name and location – Firefox, and /usr/bin/firefox. Again, if you don’t know the location of the firefox binary, in a terminal run:

which firefox

With this done, and the preferences saved, I can now debug my scripts using Xdebug!

References:

http://www.xdebug.org/docs/install
http://www.eclipse.org/pdt/documents/XDebugGuide.pdf
http://devzone.zend.com/article/2803-Introducing-xdebug