Xdebug is a very nice extension for PHP. It makes step by step debugging possible in your IDE. For most people it’s easy to install Xdebug and start debugging their web application on localhost with some IDE, for example Netbeans. Because after installation of Xdebug, it just works. A lot of this tutorial works almost the same for PhpStorm.

But getting Xdebug remote to work if your website runs on a virtual machine / Vagrant box, it’s a bit trickier and requires a bit more configuration.

First let me explain how the Xdebug flow works. In my /etc/hosts file on my host machine I added the following line to point that example.local to the IP of my virtual machine / Vagrant box (The Vagrantfile contains config.vm.network :hostonly, “192.168.33.10″):

192.168.33.10 example.local

In my browser I open the following URL which will point to the virtual machine:

http://example.local?XDEBUG_SESSION_START=netbeans-xdebug

By opening the URL, the web server on the VM creates a connection with Xdebug to my IDE on my host machine. The Netbeans debugger listens on port 9000 by default, and Xdebug connects to that.

Configuration

Let’s make it work! Add the following settings to xdebug.ini:

xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_host=192.168.33.1
;xdebug.remote_connect_back=1 ; Use remote_host or remote_connect_back. With a local VM remote_connect_back should work also.
xdebug.remote_port=9000
xdebug.remote_autostart=0
xdebug.remote_log=/tmp/php5-xdebug.log

The Vagrant box runs on the IP 192.168.33.10. Vagrant gave my host machine the IP 192.168.33.1. So xdebug can reach my IDE on my host machine with the IP 192.168.33.1.

Restart your webserver or php5-fpm, check with phpinfo() if your configuration is really changed.

Give it a try

Click on the debug button in Netbeans or press Ctrl + F5 to start the Netbeans debugger and start listening on port 9000.

Open in your browser the URL:

http://example.local?XDEBUG_SESSION_START=netbeans-xdebug

Check on your virtual machine /tmp/php5-xdebug.log if the xdebug could connect the host machine on port 9000. It is possible that you get this error:

I: Connecting to configured address/port: 192.168.33.1:9000.
E: Could not connect to client. :-(

Sometimes if you enable/disable debugging in Netbeans a few times and you enable debugging again, Netbeans says it’s listening but it just isn’t. You can check with the following command on your host machine if something is listening on port 9000:

netstat -tln

Just close Netbeans and start it again and it should listen to port 9000 again when you click on the debug button.

Path mapping

At this moment almost everything works, but step by step debugging probably still fails. Click the right mouse button on your project in Netbeans and choose Properties -> Run Configuration -> Advanced.
Set Debug URL to “Do Not Open Web Browser”. And set the correct path mapping, I set the following:

Server Path          Project Path
------------------------------------------
/vagrant             /var/www

It also helps to take a look again at /tmp/php5-xdebug.log on your virtual machine to see on which path the PHP file is that Xdebug opens, caused by the call in your browser. Step by step debugging should be working when the correct path mapping is set.

Xdebug from the command line

It’s also possible to debug your PHP console scripts on the command line. Execute the following in your terminal:

export XDEBUG_CONFIG="idekey=netbeans"
export PHP_IDE_CONFIG="serverName=example.local"

Now you can run your PHP scripts. If you have debug mode turned on in Netbeans then the PHP script will hold until you step further in Netbeans.

Xdebug from the command line inside a (Vagrant) virtual machine

If you want to use Xdebug with command line scripts or phpunit inside the virtual machine, that still won’t work with the settings defined up till now. Because Xdebug won’t find a remote host to connect back to.

Run the following command inside the virtual machine:

netstat -rn

You will probably see something like:

Kernel IP routing table
Destination     Gateway         Genmask         Flags   MSS Window  irtt Iface
0.0.0.0         10.0.2.2        0.0.0.0         UG        0 0          0 eth0
0.0.0.0         10.0.2.2        0.0.0.0         UG        0 0          0 eth0
10.0.2.0        0.0.0.0         255.255.255.0   U         0 0          0 eth0
192.168.33.0    0.0.0.0         255.255.255.0   U         0 0          0 eth1

This tells us that the IP address that Xdebug must connect to is 10.0.2.2. So with the following example command it should work:

php -d xdebug.remote_host=10.0.2.2 phpunit -c module/Application/test

This should be all! Developing virtually should be just as easy now as developing locally! Enjoy!