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.
Let’s make it work! Add the following settings to xdebug.ini:
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.
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.
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.
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.
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!