I’ve written about Eclipse and how useful it can be, with its extensible plugin-based system. It’s so useful that I use it everyday for almost any language – Java, PHP, JavaScript to name a few. It’s even great for things like CSS and XHTML.

PHP is currently my favourite “hobby” language and has been for some time. While I like PHP, one of the things that hasn’t been straightforward with it is setting up a proper debug session, where you can step through code. This contrasts heavily with a language like Java, which has always had strong developer tools. This has resulted in a mass of third-party tools aimed at facilitating PHP debugging. A while ago, a reader emailed me asking about this very topic, so I decided to put together how-to detailing my experience with the topic and how I went about learning it.

Xdebug for PHP and XAMPP

The debugger I’ll be using will be Xdebug. Because PHP provide no built-in debugging tools, there are many third-party options for debugging. (See the “Debugging Tools” section of this article for more) However, Xdebug seems to be one of the more popular ones, and Eclipse PDT already has support for it.

This guide also assumes use of XAMPP, the great all-in-one solution for quickly setting up a web development environment and to get your code running on the server. XAMPP is great for hitting the ground running, though you’ll probably not want to use it in a production environment – though you likely won’t be debugging there either. Nevertheless, the instructions provided here should work even if you’ve setup Apache and PHP separately on your own.

Getting started

The first thing you’ll want to do is head over the Xdebug page and download the appropriate Zend extension of Xdebug corresponding to the version of PHP you’re running. Save the file into your PHP extension path/folder. Now you’ll have to edit your php.ini file to begin using the plugin. The plugin basically exposes or provides an interface for the client debugger (running in Eclipse or your IDE) to attach to the server and debug/trace through the code that’s running on it. If you’re from the Java world, you’ll know this as “remote debugging”, which is provided by most J2EE application servers.

You’ll also want to have downloaded Eclipse PDT have that installed as your IDE, if you haven’t already done so. Zend Studio for Eclipse also works, since it’s based on Eclipse PDT, and offers quite a few more features, out of the box.

Setting up Xdebug

You should have already saved the Xdebug extension DLL file to your PHP extension folder. Record down the full path of it. Now, open up your php.ini file and go down to the [XDebug] section, or create it if it’s not there. Uncomment or add the following lines:

;; Only Zend OR (!) XDebug
zend_extension_ts="D:\XAMPP\php\ext\php_xdebug.dll"
xdebug.remote_enable=On
xdebug.remote_host="localhost"
xdebug.remote_port=9000
xdebug.remote_handler=dbgp

The zend_extension_ts should point to location of your Xdebug extension DLL that you downloaded earlier; modify as appropriate.

Then, you should disable the Xdebug entry in the list of dynamic extensions. This is confusing, but since we are already setting up Xdebug as a Zend extension, we don’t need another entry. Disable the Xdebug dynamic extension by ensuring the following line is commented out, like below:

;extension=php_xdebug.dll

There is one last very important step you need to do, particularly if you are running XAMPP. Current versions of Xdebug are incompatible with the Zend optimizer that is enabled by default in XAMPP, so you must disable that if you want Xdebug to work. If you don’t, you’ll notice that Apache will crash every time you try to load it with Xdebug enabled. To disable the Zend optimizer, find the [Zend] section in php.ini and comment out all of the entries under it, like so: (This is an example, there may be more to comment out)

[Zend]
;zend_extension_ts = "D:\XAMPP\php\zendOptimizer\lib\ZendExtensionManager.dll"
;zend_extension_manager.optimizer_ts = "D:\XAMPP\php\zendOptimizer\lib\Optimizer"
;zend_optimizer.enable_loader = 0
;zend_optimizer.optimization_level=15
;zend_optimizer.license_path =

You should be able to start Apache now without troubles.

Configuring Eclipse for PHP debugging

The next part will be configuring Eclipse as a debugging client. Since the code will be executing on the web server (Apache), you’ll need Eclipse to “hook in” using the Xdebug protocol. Thankfully, configuring Eclipse is fairly straightforward.

Open up Eclipse’s preferences and go to PHP -> Debug, and ensure that XDebug is selected as the PHP debugger. This sets the default for debugging sessions and lessens the configuration required for each debug session. You can also make sure that the default web server is localhost if that’s the case, which it’ll likely be for a lot of people doing development.

Note that if you are running Zend Studio, you’ll need to follow the steps in this article to enable Xdebug support. It seems that some versions of Zend Studio by default disabled support for the Xdebug plugin in lieu of their own Zend Debugger.

Now you can select a file from a project you’d like to debug. In my case, I’ve selected src/demo/index.php from my Challenge-Response PHP Login System project. Open the file, and then go to the Run Menu and select Debug Configurations… or Open Debug Dialog.

Double click the the “PHP Web Page” entry on the left side bar to create a new debug profile. Here, I’ve named it “CHAP-PHP”. You should see a dialog like the one above. Make sure the “Server Debugger” is again set to Xdebug and that the PHP Server is set to the localhost configuration you set up previously.

Then you have to select the file you want to debug. Click on “Browse”, and you’re confusingly taken to another view of your Eclipse projects; simply select the same file as before – you have to select a specific file, and not just a project or folder.

After that, you’ll need to adjust the URL mapping. You’ll probably need to uncheck “Auto Generate”, and then enter the URL that corresponds to the PHP file you’re debugging. Here, I’ve manually entered /projects/CHAP/trunk/src/demo/ as the URL fragment that triggers execution of the script.

If you want the debugger to stop right at the first line to allow you to immediately begin stepping through code, check “Break at First Line”. (It may be checked by default) Otherwise, uncheck it if you only want the debugger to stop at the breakpoints you’ve specified in Eclipse, which is the normal behaviour most developers will expect.

You should now be able to click “Debug”, and a debug session will launch, opening up the URL you’ve specified and allowing you to step through code. If you don’t like Eclipse using its own internal web browser (which appears just be a front for IE), you can configure which web browser you’d like it to launch URLs with by opening up Preferences and then going to General -> Web Browser and changing the setting to use an external web browser of your choice. Personally, Firefox is my preference.

Start your debugging engines!

You can now get acquainted with stepping through code, which in my opinion, is one of the best ways to learn! When you launch a debug session, Eclipse should prompt you to switch to a new “perspective”, which is just a different layout of Eclipse’s internal windows that many believe better suit debugging through code.

You’re provided with an informative view of the script your currently debugging, along with the highlighted line that execution has paused on. You can set debug breakpoints by double-clicking in the left margin of your source code view window; debug breakpoints show up as blue circles here. The buttons at the top (green “Play”, red “Stop” and others) provide control over execution of the code, allowing you to step through code line-by-line, step into functions/methods and return from them. I encourage you to experiment with all of the controls and get acquainted with the keyboard shortcuts.

Another panel also shows all the current variables available to the script as well as their values. This is useful since you now do not need to echo anything to output or change any of the code to see values.

When you’re done, you can just click the red “stop” button to disconnect from the server and end the debug session. If you’ve completely stepped through a script, you will not be automatically disconnected from the server. Instead, the debug client in PHP will patiently wait to debug the script again the next time it is executed. This is useful to know, since you can just go back to the URL in your web browser and reload the page to trigger the debug session to resume again.

Conclusion

I hope you found this useful, as when I was starting out trying to get a PHP debug session to work, it was somewhat frustrating. As always, I welcome your comments, suggestions and questions below via the comments form!

References

1. Why does xdebug crash apache on every XAMPP install I’ve tried?
2. Xdebug: Documentation
3. How to enable the Xdebug debugger in Zend Studio for Eclipse
4. Debugging PHP applications with Xdebug