By way of background, Xdebug is a debugger for PHP. It works really well with PHPStorm, our present programming editor of choice, and it is incredibly handy for any PHP web developer. Setting up Xdebug to work for one developer at a time is reasonably easy, and I’ve been using it that way for a few years now. But my partner has not been able to use Xdebug at all. This article is about how I got it to work for both of us.
First, a word about our setup. We have a development server that runs Ubuntu, a flavor of Linux. Although we each have our own workstations, the local copies of all of our website files and databases reside on the development server, which we share. The development server runs Apache, MySQL and most of our tooling. A central server setup has some downsides and is by no means the only way to go, but it really helps to reduce our maintenance overhead. Because of the way this setup works, Xdebug has to run on the development server.
On its own, Xdebug will apparently only talk to one computer at a time. If you read the documentation, you may come away with the impression that by adding “xdebug.remote_connect_back=1” to the xdebug configuration file many developers will be able to use Xdebug simultaneously. This turns out not to be true. What you need to add is a proxy – a piece of software that acts as an intermediary between the many developers and Xdebug. Happily, the wonderful folks at Komodo have written one, and it’s free.
There are lots of articles about how to set this up. I read all of them. None was complete, and many were inaccurate. This is simply a record of what worked for us, on our particular setup, in hopes it may help someone in the future.
Getting Xdebug installed on the development server was easy – there’s a nice Debian/Ubuntu package in the official repositories (php5-xdebug if you’re looking). You may need to tweak the xdebug configuration file for apache (etc/php5/apache2/conf.d/20-xdebug.ini on our box). Here’s what ours says. I am not sure that all of the lines are necessary, and others may be desirable, but I can tell you NOT to add an “xdebug.idekey” value, as it defeats the whole purpose of this exercise:
zend_extension=xdebug.so xdebug.remote_enable=1 xdebug.remote_host=localhost xdebug.remote_port=9000 xdebug.max_nesting_level = 256
After you have installed Xdebug, you need to install the DBGp proxy server. Download the “Python Remote Debugging Client” from here: http://code.activestate.com/komodo/remotedebugging/ Choose the package appropriate to your operating system. In our case, this was the Linux (x86_64) package. Getting this to work on our Ubuntu server was a bit of a chore – it does not work out of the box. I extracted the downloaded files to a convenient spot (the bin folder of our home directory) and created a bash script that reads as follows:
#!/bin/sh cd /home/[USER]/bin/Komodo-PythonRemoteDebugging export PYTHONPATH=./pythonlib:./python3lib:$PYTHONPATH python pydbgpproxy -i 0.0.0.0:9001 -d 9000
The first line of code changes to the directory where I extracted the downloaded files. Your mileage and file structure may vary. The next line helps pydbgpproxy find its own libraries. The last line starts the proxy server, and tells it how to listen for developers (the -i parameter) and how to talk to Xdebug (the -d parameter). The instructions found elsewhere on the internet for the “listen for developers” part is often wrong. Just put “9001” and it will only listen for connections from localhost; not helpful if you’re trying to connect from a different computer. Specify a particular address (either by IP or hostname), and it will only listen for connections from that address; not helpful when the developers on the local network have different hostnames/IP addresses. Specify a subnet (e.g. “192.168.1.0”) and it still only listens to localhost. Specify 0.0.0.0 and it will accept connections on port 9001 from anyone. Do be sure you are running a good, well-configured firewall, ok?
You probably want to run this script when your server boots. That’s a different topic and is in any event specific to your setup.
Finally, configure PHPStorm on each computer that needs to use the debugger (I’m using PHPStorm 2016.1.1 right now – the locations of these commands seem to change depending on your version). Under Languages & Frameworks / PHP / Debug, change the Xdebug port to 9001. Drill down further to DBGp Proxy, and change the IDE Key to one that is unique to the computer you are setting up (i.e. something other than “PHPSTORM”). Enter the IP address of the server that’s running DBGp and 9001 as the port. Hit OK. Finally, go to Tools / DBGp Proxy, and click “Register IDE”. If everything is set up correctly and working, you should get a message: “IDE successfully registered.”
From there on in, you have a normal Xdebug setup. You will need bookmarks in your browser (Firefox) or a browser extension (Xdebug helper for Chrome) to trigger the start of a debugging session; remember to use the unique IDE Key you set above. And you need to tell PHPStorm to listen for incoming debugging connections (in my version of PHPStorm, this is a little telephone icon in the toolbar).
Happy debugging!