Setting up xDebug with PHPUnit using Docker for Mac and PHPStorm
Although PHPStorm has done a great job with the zero configuration debugging for web server applications, it’s not quite that easy (for me any way) for CLI applications, particularly when using Docker for Mac as the CLI Interpreter.
TL;DR
It basically came down to the remote host (provided automatically by PHPStorm and the ‘zero config’) not working with the debugger. The Advanced Settings and “Pass required configuration options through command line” should be disabled and you should provide your own configuration options to your Docker CLI interpreter.
xdebug.remote_enable=1
xdebug.remote_host=docker.for.mac.localhost
xdebug.remote_port=9000
xdebug.remote_mode=jit
Background
Getting set up with docker to run all my PHPUnit tests was a breeze and actually saved me a load of time (previously I would run it from the terminal (running a docker container and going back-n-forth didn’t help with the RSI in my wrists). Watch that tutorial (props to @GeeH).
However, as I found with most of these tutorials[1][2][3], they are mostly geared for web based applications, my app doesn’t have a web interface only CLI which is tested using PHPUnit.
When running ‘Debug’ I would see the debug console “Connection with Waiting for incoming connection with ide key” and then once the test finished, I would get an event error “Connection with 'Xdebug 2.2.5' was not established”.
After digging through each of the xdebug configuration options and trying all sorts of combinations I finally figured out it was an issue with how PHPStorm was sending the PHPUnit request to the CLI
docker://docker/php5:latest/php \
-dzend_extension=xdebug.so \
-dxdebug.remote_enable=1 \
-dxdebug.remote_mode=req \
-dxdebug.remote_port=9000 \
-dxdebug.remote_host=ab00:0:0:0:0abc:ab1c:1a23:12a0%utun3 \
/usr/local/bin/phpunit
--configuration /app/phpunit.xml
/app/tests
--teamcity
The 'remote_host' was being set automatically but for some reason PHPStorm just wasn’t listening.
After providing the configuration options manually via the CLI using 'xdebug.remote_host=docker.for.mac.localhost' it suddenly worked and I started receiving debugging data! Happy days. It was working.
However, looking carefully, the automatic CLI configuration options were still being provided (i.e. 'xdebug.remote_host' was being sent twice):
docker://docker/php5:latest/php \
-dzend_extension=xdebug.so \
-dxdebug.remote_enable=1 \
-dxdebug.remote_mode=req \
-dxdebug.remote_port=9000 \
-dxdebug.remote_host=ab00:0:0:0:0abc:ab1c:1a23:12a0%utun3 \
-dxdebug.remote_host=docker.for.mac.localhost \
/usr/local/bin/phpunit \
--configuration /app/phpunit.xml \
/app/tests \
--teamcity
I guess I was lucky that it worked as the manual config options came after the automatic config (kinda makes sense).
Although it was now working and I was getting valuable debugging data, I wanted a clean and easily replicable setup and this wasn’t ideal (things could change in future PHPStorm updates and this could break).
Firstly, I found the setting where the automatic options were being provided, it is tucked away in Preferences > Languages & Frameworks > PHP > Debug > Advanced Settings (scrolling required!).
Unchecking this and the only configuration options were now coming from the CLI settings (manual):
docker://docker/php5:latest/php \
-dzend_extension=xdebug.so \
-dxdebug.remote_host=docker.for.mac.localhost \
/usr/local/bin/phpunit \
--configuration /app/phpunit.xml \
/app/tests \
--teamcity
Debugging stopped working at this stage but at least I knew why, I needed to provide the port and other options. After a bit of tinkering I have settled with the following settings:
xdebug.remote_enable=1
xdebug.remote_host=docker.for.mac.localhost
xdebug.remote_port=9000
xdebug.remote_mode=jit
To set this configuration options, go to Preferences > Languages & Frameworks > PHP > CLI Interpreters

NOTE:
This solution worked for me, I can't say it will work for you or even if it is recommended but it does seem to be unique to using PHPUnit with Docker for Mac as the CLI interpreter using PHPStorm for Mac (a real tongue twister).
Hope this helps someone.
Please sign in to leave a comment.
Man, you saved my life! That 'required configuration checkbox' is the devil.
I do not know how to thank! You're my idol!
It's working on mac. which it great. But then if it only work on mac, it defeat the purpose of docker :(
@Budi Arsana
The only Mac specific thing that I see is docker.for.mac.localhost as a host.
Use new value instead (should now work for all OS)
WOW awesome, using your suggestion also work. Thanks Andriy Bazanov