Getting Xdebug to work with Apache/XAMPP to debug PHP

xdebug-logo

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.

php-debug-1

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.

php-debug-2

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.

php-debug-3

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

25 Comments »

  1. [...] Getting Xdebug to work with Apache/XAMPP to debug PHP » unitstep.net [...]

  2. Thanks peter! This was very helpful!

  3. [...] Getting Xdebug to work with Apache/XAMPP to debug PHP Tags: Computer Engineering, Linux, PHP Category: Computer Engineering, Internet, Linux  |  Comment (RSS)  |  Trackback [...]

  4. Thanks worked straigt a way!!!

  5. Hi,

    I’ve installed Eclipse with XDebug Under Xampp following your tutorial but when it comes to define the PHP Executables I got stuck , I do not know Where / How to get them !?

    many thanks

  6. Amazingly simple … and it is actually debugging,

    Thanx a bunch :)

  7. how to enable cookies in xampp server?

  8. http://munim.tumblr.com/post/917355998/how-to-setup-xdebug-on-xampp-and-eclipse

  9. Newer version of PHP does not work setting up XDebug with PHP.

    See http://munim.tumblr.com/post/917355998/how-to-setup-xdebug-on-xampp-and-eclipse

  10. Thanks for the great tips, always comes in useful for new installations!

    Cheers.

  11. Mr. Chng, I love you. I had almost resigned myself to doing all my debugging with echo printouts, but finally it works!

  12. Thanks a lot.
    Works fine for me !

  13. WOW! The best I have read in weeks. Thank you for the awesome write up!!

  14. I just found your article which is very consistent with and much clearer than others I’ve been reading.
    I’ve just installed in my new XAMPP on a Windows7 Gateway NV53 laptop with the following at the end of php.ini. I have verified that the other settings you mentioned are not set.

    [xdebug]
    xdebug.remote_enable=1
    xdebug.remote_host=”localhost”
    xdebug.remote_port=9000
    xdebug.remote_handler=dbgp
    zend_extension_ts=”D:\xampp\php\ext\php_xdebug-2.1.0-5.3-vc9-x86_64
    .dll”

    When I start XAMPP, Xdedug is not listed.
    When I do “D:\xampp\php> php -m” xdebug is not listed. Is this a peculiarity of Windows 7 or 64-bit? What can I do?

    Thanks.

  15. @Tom Widlar

    Hey Tom, try “zend_extension” instead of “zend_extension_ts”

  16. don’t be use the xdebug

  17. XDebug does not receive any testing from the Zend Studio team. I hope for their sake that they change this policy. Read more:

    http://forums.zend.com/viewtopic.php?f=59&t=24113&p=108183#p108183

  18. [...] http://unitstep.net/blog/2009/01/26/getting-xdebug-to-work-with-apachexampp-to-debug-php/ [...]

  19. [...] http://unitstep.net/blog/2009/01/26/getting-xdebug-to-work-with-apachexampp-to-debug-php/ [...]

  20. Thanks man! As a Java/Eclipse developer I have always hated working in php because I have never been able to get a decent debug setup working. “if(1) print_r($blah)” == stone age. Your post helped me finally piece together a working debugging environment. I can’t tell you how many other times I have tried and failed.

  21. Thank you very much for this article. It was very helpful.

  22. Thank you very much peter, this is very help..

  23. Thanks for the god article
    Also i recommend to look at the following free PHP debugger:
    Codelobster PHP Edition

  24. Thanks for the article. I used XAMPP 1.7.4 and NetBeans IDE 7.3 with the following settings in php.ini

    [XDebug]
    zend_extension = “C:\Users\XXXX\xampp\php\ext\php_xdebug.dll”
    xdebug.remote_enable=1
    xdebug.remote_host=”localhost”
    xdebug.remote_port=9000
    xdebug.remote_handler=dbgp

    Note I used “zend_extension” instead of “zend_extension_ts” and “xdebug.remote_enable=1″ instead of “xdebug.remote_enable=yes”

  25. Great help from your side.

    I was reading many blogs over the past few days and was having trouble configuring it but your tutorial made it worked.

    Thanks a lot

Post a Comment

(required)

(will not be published) (required)

XHTML tags allowed: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Note: rel="nofollow" will be added to all links in comments.