Xdebug – Remote Debugging

As a follow up from my last post Xdebug – Installation and customization this post is about configuring xdebug and a php editor (eclipse PDT) in this case to be able to do interactive debugging. Having worked as a Java Developer for quite some time, this was always something that I found missing in php or maybe I didn’t look hard enough. I have been using Xdebug for debugging code for a while now and it has actually affected my productivity quite dramatically. I am documenting the process of setting this up for anyone who might find it useful.

So just to give you a background of what really happens when you are using Xdebug for debugging. Loading xdebug as a zend module allows it to hook into the execution of php scripts. This means that you can really send the module instructions to pause and resume the execution. Also since it hooks into the execution it has access to all the variables at the time of execution which obviously is very useful for debugging purposes.
Xdebug is called a remote-debugger because the client doesn’t have to run on the same server as the webserver (or php instance running the script). The client and server communicate via their own protocol which is either GDB or DBGp. We will be using DBGp since Eclipse PDT supports it out of the box. To start the session the script needs to be called with the parameter XDEBUG_SESSION_START and similarly to stop it, it needs to be called again but with the argument XDEBUG_SESSION_STOP. There are firefox extensions that will do that for you so its worth looking into it, however Eclipse PDT (and possibly Netbeans) does that for you out of the box. Once triggered the client/server communicate via the chosen protocol and you can see your values in the debug perspective.

So lets start off by configuring the server side of things. Lets have a quick look at some of the ini settings that I had show in my previous post and had mentioned they will be covered in the next post.

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

Lets walk though the set of parameters required:

xdebug.remote_enable: This enables the remote debugging mode. This will enable triggering of debugging by passing the above mentioned arguments
xdebug.remote_host: You can specify the client hostname or IP address. This will get the server to connect to this client to pass the debugging information. This can be handy when your server is on one box, your scripts are running on another one (via selenium for instance) and your debugging tool is running on another box. This might look like a limiting feature that it only listens to the IP address mentioned in the config. However you configure xdebug to be able to start debugging from a request coming from any other host by setting xdebug.remote_connect_back to 1. This will make xdebug use $_SERVER['REMOTE_ADDR'] find out where the request came from and talk to the client. This obviously means, DON’T TURN THIS ON IN PRODUCTION.
xdebug.remote_port: This is the port at which xdebug tries to connect to the remote host. 9000 i usually the default value for most clients so its best not to change this unless you have to get around some crazy IT firewall rules.
xdebug.remote_handler: Is to define the protocol to use. The default is dbgp so you can get away without having to make this entry unless you want to change it to the older protocol for some reason

That’s pretty much all you need to do from the server side of things. Obviously if you are using apache, then you need to reload the configuration so that the ini files get re-read again with the new settings:

$ sudo /etc/init.d/apache reload

The next step is to configure Eclipse to debug. Rather than explaining it, I am listing screen-shots of configuration from my eclipse editor. My current eclipse build is: Build id: 20090920-1017. Click on the individual images to see their bigger versions.