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

Hello world!

Welcome to my blog about web development.

Here i will share different thoughts, ideas and code snipplets. Additionally I will also post some brief instruction or installation guides for useful development tools.

You are very welcome to comment my posts and to share your thoughts!

You want to know about my person? Please checkout this page or have a look on my profiles on Facebook, Google+ and Linkedin which you can find on the left hand side.

Future code snipplets, will be more interesting and challenging ;) !