XDebug for PHPUnit in Docker with PHPStorm

[ update ] Set the IP-address to the following DNS-name: docker.for.mac.localhost (yes, literally)!
Working with the IP-address doesn’t work anymore
[ /update ]

Want to get XDebug working for your PHPUnit tests which run in Docker? Or for behat? Or any other CLI application? Follow me!

Roughly this is what you’ll need to do:

1. set path mappings in PHPStorm for your Docker container
2. export $PHP_IDE_CONFIG in your container
3. export $XDEBUG_CONFIG in your container

tl;dr

Set the needed variables and execute your application.

$ VARS="XDEBUG_CONFIG=\"remote_enable=1 remote_host=docker.for.mac.localhost\" PHP_IDE_CONFIG=\"serverName=Docker\""
$ docker exec -it dev bash -lc "$VARS; vendor/bin/phpunit"

Not working? Then check whether everything came through.

$ docker exec -it dev bash -lc "$VARS; php -i | egrep 'xdebug.remote_host|xdebug.remote_enable'"
xdebug.remote_enable => On => Off
xdebug.remote_host => docker.for.mac.localhost => localhost

Set path mappings in PHPStorm

First you need to create a server and set the path mappings for your Docker container. You do this by creating the server in Settings / Preferences | Languages & Frameworks | PHP | Servers.

Export $PHP_IDE_CONFIG

In your docker container, export the PHP_IDE_CONFIG variable.

This variable will tell PHPStorm which server to use from its configuration for debugging.

Where ‘Docker’ is the name you gave to the server configured at ‘Settings / Preferences | Languages & Frameworks | PHP | Servers’ in the step above.

Windows:
set PHP_IDE_CONFIG="serverName=Docker"
 
Linux / Mac OS X:
export PHP_IDE_CONFIG="serverName=Docker"

Test to be sure.

$ docker exec -it dev bash -c 'echo $PHP_IDE_CONFIG'
"serverName=Docker"

Export $XDEBUG_CONFIG

Get the ip-address of the host running your IDE like PHPStorm.

In your dockercontainer, put the address in the command underneath and execute it on the Docker container running PHPUnit / behat / CLI.

export XDEBUG_CONFIG="remote_enable=1 remote_host=<ip_of_host_running_the_IDE>"

In docker-compose.yml add the following to your environment:

----%<-----
environment:
    XDEBUG_CONFIG: remote_enable=1 remote_host=docker.for.mac.localhost
---->%-----

Test to see whether the values are set correctly

$ docker exec -it dev php -i | | egrep "remote_enable|remote_host|remote_port|remote_log"
xdebug.remote_enable => On => Off
xdebug.remote_host => docker.for.mac.localhost => localhost
xdebug.remote_log => no value => no value
xdebug.remote_port => 9000 => 9000
XDEBUG_CONFIG => remote_enable=1 remote_host=docker.for.mac.localhost
_SERVER["XDEBUG_CONFIG"] => remote_enable=1 remote_host=docker.for.mac.localhost

Don’t forget to turn on the debugging-listener in PHPStorm 🙂