Remote Debugging phpunit tests on a Vagrant box


For quite a while now I am a huge fan of Vagrant. Vagrant helps your to create a development environment based on a VirtualBox VM (or, if you like even VMWare). That’s great, because I can commit the definition of my environment to an SCM like GIT and my colleagues can work with exactly the same environment without dealing with installing all software manually. For PHP projects I use PuPHPet, which is a web-based gui for quickly creating the necessary Vagrant files.

I love my xdebug php debugger even on commandline. Unfortunately it caused me some headache to find out why IntelliJ succeeded in remote debugging when a request came from the web browser but failed when it came from PHPUnit.

By default, PuPHPet creates an xdebug.ini which looks similar to that:

xdebug.default_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 1
xdebug.remote_enable = 1
xdebug.remote_handler = "dbgp"
xdebug.remote_port = 9000

I read the documentation of Xdebug. Xdebug will try to reconnect to the client which made the request. Unfortunately when I run PHPUnit from inside my VM there is no such client. The trick is to find out what IP my original host running IntelliJ has.

On my VM shell I typed:

$ netstat -rn
Kernel IP routing table
Destination  Gateway  Genmask

For this post I removed a few portions of the output. This table tells me my Gateway is That’s the IP I needed.

I first followed the setup in Intellij (or PHPStorm). Then I needed to override the remote_connect_back setting and tell xdebug where it should connect. A simple bash script would help me here:

export XDEBUG_CONFIG="remote_connect_back=0 idekey=intellij remote_host="
export PHP_IDE_CONFIG="serverName=yext.local"
vendor/bin/phpunit --bootstrap tests/bootstrap.php --stderr tests/$1

Inside XDEBUG_CONFIG you’ll find a blank-separated list of configuration. Now I was able to debug the web browser provided by the presets and even my cli scripts. Finally I would like to recommend you this extremely smart Chrome browser plugin.

Tags: #intellij #PHP #phpunit #xdebug