Remote PHP Debugging via Eclipse PHP and Xdebug

Ever dreamed about debugging the php app on live? With Xdebug it becomes possible to actually debug a remote (deployed) php app on your development pc. Here I am going to show you how to do that.

As in my another blog, you will have to setup Xdebug on your php server to be able to debug php in the first place. The key concept is, the ability of php debugging comes from server provided by Xdebug. While Xdebug supports a variety of debug clients, Eclipse is only one of them and used here as an example.

Normally as a programmer, we have a full development stack in our development environment which comprises of apache, php(with Xdebug), mysql and Eclipse as IDE. That is all good.

What I am talking here is that apache and php is on a remote pc, or even a shared host, and Eclipse is on your own local pc with no direct file access to the remote pc, how are we going to debug app on that remote box?

To make it happen all you need to do is as following:

1. To have Xdebug on your remote php installed, I am not sure if you can do this on a shared environment, but in our case we have full control of the server, so it is not an issue
2. To config Xdebug to support remote debugging, here is my php.ini in regards to Xdebug:
zend_extension = C:\php-5.3.3-nts\ext\php_xdebug-2.1.0-5.3-vc9-nts.dll
xdebug.remote_enable = 1
xdebug.remote_host = “”
xdebug.remote_port = 9000
xdebug.remote_handler = “dbgp”
xdebug.remote_mode = req
xdebug.remote_connect_back =1

2.1. Your Xdebug dll might be of a different version or from a different place

2.2. Set remote enable as true

2.3. Remote_host: this is ip address of your debug client, where your eclipse is
When remote_connect_back is not on, then it limits only remote_host pc can debug, in my case, remote_connect_back is turned on, which means all the remote debug requests will be accepted, therefore remote_host limitation will be ignored

2.4. Remote _port always uses 9000 as it is widely accepted as default, using default will save unnecessary configs in eclipse later on, this requires your local pc or your local network to open the port of 9000 for xdebug to call in

2.5. ‘dbgp’ is the protocol eclipse supports to talk to remote xdebug

2.6. Remote_mode will decide if the debug session starts as requested or automatically

2.7. Remote_connect_back is turned on, I assume that you understand the consequence of this, debug request from any source will be accepted by Xdebug, obvious you can turn it off when you do not need to debug.

2.8. Confirm all these settings from phpinfo() Xdebug section.

3. Make a copy of the deployed php project on your local, this is needed as debug client cannot have direct file access to php files on the remote server, but a local copy is needed to actually allow eclipse to have access to code, for c# applications, the files must match exactly with remote ones, but for php, the match only matters to the lines you want to debug.

Place that copy in eclipse workspace.

4. No it is time to config your eclipse to talk to that server
In eclipse workspace, right click the php file you want to debug and choose Debug as -> Debug configuration…

Debug Configuration

Debug Configuration

4.1. Server debugger: Xdebug

4.2. Php server: new

Remote Debug Server

Remote Debug Server

4.3. Details for your php server

4.4. Php server url: the trunk url of your deployed app

4.5. Php server Path mapping : no need to set, magically when first time the debug is run,
the mapping will be remembered

4.6. File – browse to the file you want to debug in your workspace

4.7. url auto generate checkbox – ticked, and from the greyed boxes underneath, you can see the final url, it must match with your remote url of the debugged file, you can change the project folder in your work space, or change the server url in php server setting to adjust

5. click debug, you should be able to debug the app on a remote server.

This entry was posted on Friday, March 4th, 2011 at 2:31 am and is filed under PHP, Software Engineering. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

3 Responses to “Remote PHP Debugging via Eclipse PHP and Xdebug”

  1. Syrgak says:

    Hi! Thanks for taking time to put this how-to up online. The idea is great! Could you just elaborate a bit as of its purpose. As I get it, it is to debug php code on a remote server in “read-only” mode? Remember, you dont have direct access to the remote files! As soon as you start making changes (i.e. fixing bugs) the local copy does no longer match the one on the server and you cannot debug anymore. The alternative would be to upload local copy everytime there’s a change. But that in turn defeats the whole point of debugging. Please, correct me if I’m wrong here.

    Cheers, mate!

    • CleanCodeNZ says:

      Hi there:

      Good questions.

      Remote debugging usage is highly conditional, it depends on server and client firewall settings for this to be possible, you are right that we need to keep two copies matching, sometime, you do not have to make changes on live, and it is not recommended as well, but to use the data and environment settings from live to just watch internal values is very useful for trouble shoot, some time it is hard if possible to duplicate the same environment in your development.

      By saying that I agree with you remote debugging’s use should be over exaggerated


  2. I suggest to try Codelobster to debug PHP.
    It has very convenient free PHP debugger.

Leave a Reply