First we will cover how to enable PHP remote debugging in PHPStorm if Vagrant is used and because this is so easy we also write a short Shell script to use remote PHP CLI debugging e. g. for Cronjob scripts or unit tests.
If you don't have a Vagrant box you can use my vagrant-librarian-puppet example. If you use this Vagrant box you can skip "Enable Xdebug PHP extension" and the URL is
Enable Xdebug PHP extension
To enable debugging you must configure Xdebug. Make sure you have installed the PHP Xdebug extension (
sudo apt-get install php5-xdebug). Open your
/etc/php5/conf.d/20-xdebug.ini (path depends on OS) and add the following lines:
xdebug.default_enable=1 xdebug.remote_enable=1 xdebug.remote_handler=dbgp xdebug.remote_host=10.0.2.2 xdebug.remote_port=9000 xdebug.remote_autostart=0 xdebug.remote_connect_back=1
The important point is
xdebug.remote_host which can change on other system configurations, but it should work for the most common use cases. This IP address is the gateway of the vagrant box.
Remote PHP debugging
To start debugging you must set a cookie because autostart debugging is not enabled. There is a great Firefox add-on "The easiest Xdebug". If the cookie is set and you have enabled listening for incoming debug connections in PHPStorm a popup window should appear to configure your PHP servers. To avoid upcoming popups open the settings
File -> Settings -> Languages & Frameworks -> PHP -> Server and remove the path of the file and set only the project root path. Don't forget to set a breakpoint in your PHP file.
Remote PHP CLI debugging
A Shell script is necessary for remote CLI debugging. Please create a file in your vagrant box with name
cli_debug.sh and put the following lines in this file.
#!/bin/bash export XDEBUG_CONFIG="idekey=PHPSTORM" && export PHP_IDE_CONFIG="serverName=application" && php "$@"
To enable debugging you must specify the
idekey and the
serverName. PHPStorm uses the
serverName to determine the right server. Copy the previous server config and rename it to
Make this file executable with
chmod +x cli_debug.sh and now you can start debugging of PHP CLI scripts with
./cli_debug.sh [Path to your PHP file]. If you use the vagrant-librarian-puppet example you can test it with
./cli_debug.sh /vagrant/public/index.php. Don't forget to set a breakpoint in your PHP file.
Vagrant SSH connection timeouts
On Windows 7 I have sometimes SSH connection timeouts. To solve this problem cancel the Vagrant up process (Strg + C) and execute
vagrant reload or stop the box in VirtualBox and start it again with
vagrant up, then it works. I don't know why this happens.
Article picture: code bug by gui.tavares under CC BY-NC 2.0