Remote debugging in PHP with Xdebug

I like to start my blog with a small tutorial where i do explain, how you can debug remotely in PHP using Xdebug.


Especially Java and .NET developers are familiar with many good tools to debug their application. When we talk about web development debugging is not as easy as it is i.e. for desktop applications, because we often have server-side code.

Microsoft’s Visual Studio starts a local server and does automatically connect to this process for debugging your code, when you develop a web application. In PHP you do not have a local server by default. You can install a AMP-stack on your machine for developing local, but your IDE does not automatically connect to the webserver and listen to debug events. You have to install additional software to enable debugging on a local machine. There are different options [1]. I personally prefer Xdebug [2]. One reason is that you are able to debug remotely with Xdebug.

Show: The future – a php-build-in-werbserver »

Please note that with PHP 5.4 a php-build-in webserver will be available. I guess there will be an option to use it for debugging in future!

Debugging locally is a nice improvement to have no debugger at all, but in many situations there is the need to debug on production server, where the application is running on the web. There are different reasons for that, but the most important one for me is, that my local environment / installation is different from the one i have on servers in data center and bugs can be related to the environment.


Installing Xdebug is very easy, because Xdebug is a available as PECL extension. (Note that the following commands for debian/ubuntu may be slightly different for other linux distributions):

To install a PECL extension you need to install PEAR first. Be sure that you have installed PEAR and continue then with installing the Xdebug PECL extension:



After the installation is finished open your php.ini and add the following line to the extension section:

Please do not miss that you have to use ‚zend_extension‘ instead of ‚extension‘ and that you have to replace {BUILDDATE} with the date you found in your php5 lib folder.

Congratulation, you have installed and configured Xdebug with a basic setup. Before continueing with additional steps and settings, i recommend to read the following advices:

Show: Important notes on remote debugging »

Do not set ‚xdebug.remote_autostart‘ to ‚1‘, because every visitor of your page would start an Xdebug session then. This is annoying and can be a serious performance problem. If ‚xdebug.remote_autostart=0‘ and ‚xdebug.remote_mode‘ set to ‚req‘ everybody who set the GET/POST/COOKIE variable can start a debugging session. Obviously normal visitors would not do that, nevertheless i suggest to avoid that by setting-up a second virtual host with a testing system which is a clone of your production system. Both virtual hosts can still share a common php.ini where you set ‚xdebug.remote_enable‘ to ‚0‘. To enable remote debugging for the virtual host of your testing system, set ‚php_flag xdebug.remote_enable on‘ in virtual host configuration.

Debugging Proxy

When you are working alone you are now able to use Xdebug, but when you work in a team where multiple people like to debug parallel or from different machines you have a problem, because you can only enter one IP address in php.ini as xdebug.remote_host. Since changing the IP address in the configuration file or sharing a single machine for debugging is not a nice solution, you should install a proxy for Xdebug. With this proxy you are able to connect with multiple machines at the same time to Xdebug and open multiple parallel debugging sessions. (Attention: you have to set xdebug.remote_handler to ‚dbgp‘ if you like to use the proxy.) Komodo offers such a proxy. Please download the ‚Python Remote Debugging Client‘ which does fit to your server sytem [3].

Extract the files and locate the pydbgpproxy file. If necessary apply:

Now, you can start the proxy with the following command:

eee.fff.ggg.hhh is the public IP of the server, 9001 is the port on which the proxy is listening for connections of debugging clients, is your local loopback address and 9000 is the port on which the proxy is listening to debugging sessions from Xdebug. Please do not forget to reconfigure your php.ini and to change the ‚xdebug.remote_host‘ to the loopback address ‚‘, too! If you like to make sure, that the proxy is running after a reboot, do not forget to write a start script for that purpose or to add an entry in your crobtab.

Show: Security Risk Proxy »

If you enable your proxy to listen to the public IP address, foreigners can register with your proxy and attach themselves to debugging sessions. Although the risk, that this happens is not that big, i recommend to create a virtual private network and add all developers and your server to it. Then you can configure the proxy to only listen on connections from machines in your VPN.


To debug your application you still have to configure your IDE. How to configure it in detail depends on your IDE. In general you have to set the server IP ‚eee.fff.ggg.hhh‘ and the port (9001). You should also set an unique ‚ide key‘ for each machine to ensure that, when you work in a team, your IDE gets only attached to debugging sessions started by yourself. In some IDEs you also have to enable the debugging mode by making the IDE listening to connections from the debugger and to manually register to the proxy with your IDE first.
To initiate a debugging session you now have to set a GET/POST/COOKIE variable in your favorite browser. Since GET and POST variables are used to control the flow of your application and get lost with every page change, i recommend to set COOKIE variables. There are useful browser extensions for setting these variables automatically (i.e.: Xdebug helper for Chrome [4] or easx Xdebug for Firefox [5]). When you configure them do not forget to set the ‚ide key‘ to the same value as you set in your IDE!

To have a good debug experience you should take care, that the code on the developer machine is the same as on the server. If this is not the case debugging will fail.

Now Xdebug including a proxy is installed and configured and you can start your debuggins sessions.

I hope you like this tutorial, and please do not hesitate to ask your questions or to comment this post. Happy debugging!

Useful links

3 Gedanken zu „Remote debugging in PHP with Xdebug

  1. giuspe

    a small note/hint: if you have ssh access to the (remote) machine you want to debug, you can avoid using a proxy by opening a ssh session w/ some port forwarding magic…

    you can simply open a ssh connection – via terminal (in Linux / OsX) or using some tool like WinSCP in Windows – adding a port-forwarding option, like this

    ssh -R 9000:localhost:9000 [username]@[IP or address]

    that will prompt each time for your password, unless you share a public key with your server (here’s a short tutorial on that).

    have fun debuggin‘!

    1. Markus Pullmann Beitragsautor

      Hey giuspe,
      thanks for this smart hint. If you run establish this port 9000 forwarding command you do not need to set-up a proxy, because all incoming connections on port 9000 from the host who established this connection are forwarded to port 9000 on localhost (server-side). You just have configure Xdebug to listen on port 9000 on your localhost. It is very useful in small to medium development teams.
      If you are working in a large team it is a bit annoying to have everybody to establish this connection, especially if you like to debug on different / multiple servers. In this case i recommend to setup a virtual private network (VPN) with a debugging proxy, like i mentioned before.


Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.