How to debug code on a remote server (or in vagrant box) with PHPStorm

Please also note: There are several methods to do remote debugging. This is the one that works without any browser plugins etc. and integrates seamless into your PHPStorm-&-Vagrant-workflow.

Requirements

You have part 1 of this tutorial (How to setup a professional local server (in a virtual machine) with Vagrant in PHPStorm) successfully finished, therefore you have PHPStorm open and a Vagrant box running.

Setting up xdebug on the server

Start your Vagrant box (Tools > Vagrant > Up) and log into your box via SSH (Tools > Start SSH session). As we have used Ubuntu 12.04 (Precise Pangolin) while installing this box, we can install xdebug easily with a one-line-command:

sudo apt-get install php5-xdebug
sudo service apache2 restart

Unfortunatly, we ll have to enter some configs into the php.ini manually now (why is linux/xdebug not doing this automatically ???). Open the php.ini with sudo rights:

sudo nano /etc/php5/apache2/php.ini

Your php.ini is somewhere else ? Find it that way:

find / -name 'php.ini' 2> /dev/null

Scroll down to the end of the file and add the following:

[xdebug]
zend_extension="/usr/lib/php5/XXXXXX/xdebug.so"                                  
xdebug.default_enable = 1                                                            
xdebug.idekey = "PHPStorm"
xdebug.remote_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_port = 9000
xdebug.remote_handler=dbgp
#xdebug.remote_log="/var/log/xdebug/xdebug.log"
xdebug.remote_host=YYYYYYYYYYYYY

The path in the first line is the location of the xdebug.so file, you can find the path via

find / -name 'xdebug.so' 2> /dev/null

For easy handling simply mark the result of “find” with the mouse, it’s then automatically copied in the clipboard. The last line contains your IP, which means the public IP of your computer you are running PHPStorm on [it’s also possible using the private internal IP, but I’m not sure about it]. Find your IP easily via

http://www.whatismyip.com/

Note: Your IP might change every 24hrs, depending on your internet provider. When your scripts seem to “load forever”, then your IP might have changed.

Restart the server:

sudo /etc/init.d/apache2 restart

Remote debugging time

After you have restarted the apache, click on the little “telephone icon” in the menu bar in PHPStorm. PHPStorm will now listen for incoming debugging sessions (from the Vagrant server, which know your IP and will therefore be able to communicate with PHPStorm).
It’s extremely important to click that icon, otherwise a) PHPStorm will not be able to debug your remote code and b) your remote scripts will “hang” and wait forever… Set some red markers left to some lines in the code and run a php file on your server, like

http://192.168.33.101/index.php

and see the debugging box pop up in PHPStorm. Yeah! Business as usual here: Press the green triangle on the left side to go on with the application (F9) or press the red square to completely stop running the app (CTRL+F2). By the way, it’s also possible to override all markers with the two-red-circles icon or manipulate variables by right-clicking them.

When suddenly the server is “not reachable” anymore

Probably your IP changed and xdebug hangs therefore. Check your new IP and change it in the php.ini, restart the server. Everything should work fine now.