PHP remote debugging with Xdebug and Eclipse PDT

Debugging is an invaluable part of software development. I find it very useful in a variety of situations, for instance when I want to understand how a routine works or I need to get rid of a bug that is not exactly easy to fix just by reading the code.

There are several ways to perform debugging in PHP:

• The most straightforward technique is to use print_r() and var_dump(). This will alter the output, it's quick but very dirty. If you're using this there's nothing to be ashemed of, everyone is doing it.
• Logging into files/database tables at specific points in the code. This is cleaner than the previous method, but it requires additional effort and usually polutes the code with logging routines. Also this is not exactly debugging, it's logging and analisyng the logs.
• Using proper debugging tools like Xdebug or the Zend Debugger, integrated into your PHP IDE. This is the clean way to do it, it provides a much better insight into the source code, as you can run it interactively, step by step.

My main goal in this post is to show you how to set your debugging environment with Eclipse PDT and Xdebug. If you're not already using it, get your Eclipse PDT from http://www.eclipse.org/pdt/downloads/ and install it. Next you will have to get and install xdebug on the machine where PHP runs(it can be the same machine or some remote machine). You should be able to get it through PHP PECL with the following command:

pecl install xdebug

If the above does not work, check the Xdebug installation instructions at http://xdebug.org/docs/install .

Once the xdebug extension was installed, you will have to add the extension to php.ini. Add the following lines to php.ini:

[xdebug]
zend_extension=/path/to/xdebug.so(.dll)

xdebug.remote_enable=On
xdebug.remote_handler="dbgp"
xdebug.remote_mode="req"
xdebug.remote_port=9000
xdebug.remote_host="YOUR.IP.GOES.HERE"
xdebug.remote_log=/path/to/xdebug_remote_log

Update:
On Windows+PHP 5.2.14 I had to replace zend_extension with zend_extension_ts:
zend_extension_ts="c:\\php\\ext\\php_xdebug-2.1.0-5.2-vc6.dll"


Be extra careful with xdebug.remote_host, this is the host where you develop and run your Eclipse, and PHP will try and connect to Eclipse when debugging is enabled. Also make sure that the zend_extension part was not added automatically by the installation, if it was don't add it again.
If there is any mention of the Zend debugger in you php.ini file, you will have to comment that. Restart Apache or whatever web server you're using and make sure the Xdebug installation was correct by running a simple PHP script that contains phpinfo() and searching for "xdebug".

Now the tricky part, Eclipse has to be configured to accept debugging sessions from XDebug. Follow the steps below:

1. Open your project in Eclipse PDT
2. In the main menu select Project->Properties
3. On the left side of the window select "PHP Debug" and then click on "Configure Workspace Settings"
4. On the "PHP Debugger" dropdown select Xdebug and click "Apply"
5. Click "Configure" to the right of Xdebug in the same window.
6. Select Xdebug and click "Configure".
7. On the "Accept remote session(JIT)" select "any" and click "OK". This is extremely important and this is where most people get stuck.

That's it, Eclipse is now configured, now all we need is to be able to be in control of our debugging sessions. For this we will need to install a Firefox extension called "easy Xdebug"(yes Firefox, you're not developing PHP in IE are you?).

The extension can be installed from https://addons.mozilla.org/en-US/firefox/addon/58688/ . If the link does not work just google "firefox xdebug". Install the extension and restart Firefox. After that you will notice a little green bug on the bottom-right of Firefox and if you hover it it says "Start xdebug session".

As a side note, you might have used Zend IDEs where the debug process starts from the IDE. In Eclipse PDT the process is reversed: you start from the page that you want to debug and PHP will connect to Eclipse in order to establish a debug session. That is why we have installed the firefox extension, because the debug starts from the browser.

Now open the page that you want to debug, on the server where you have just configured PHP with the XDebug extension of course. Click on the green bug I just mentioned to enable debugging and then reload the page. After this you will have to go to Eclipse and see that a new window has just popped up, asking you to "Select the local resource that matches the following server path". In a simple setup you will have just a single option, select the PHP file in that window and click "OK". Eclipse will ask you if you want to change to "PHP Debug perspective" and obviously you have to say "Yes". Optionally you can also check "Remember my decision". After this you should be in the debugging perspective, with Eclipse stopped on the first line of your code, meaning that you can now step through your code.

As a simple guideline you can use the following keys:

• F5(Step Into) - steps into everything including function or method calls
• F6(Step Over) - walks through but does not step into function or method calls
• F8(Resume) - runs until the first breakpoint or end of the program

Breakpoints can be placed by double-clicking on the right of the line where you need the breakpoint. Try and play with the above keys to get a better idea of how they work.

That's it, I'm sure you'll realise that you can't live without debugging once you start using it.