Home » Php » php – Running PHPUnit within a Docker container with PhpStorm

php – Running PHPUnit within a Docker container with PhpStorm

Posted by: admin April 23, 2020 Leave a comment


I want to configure my PhpStorm IDE to run PHPUnit tests within my Docker container.

It seems like I’m restricted to either using a local PHP executable, or one through SSH, as the interpreter for the tests.

I could install an SSH service on my PHP container, but it seems like a bit of a hacky solution, and articles online discourage installing an SSH service on containers.

To try and get a local interpreter working, I tried creating a bash script that would proxy calls to PHP within the container, like this:

#!/usr/bin/env bash

# Run PHP through Docker
docker exec -t mycontainer_php_1 php "[email protected]"

This works perfectly when I run it myself, but when I point PhpStorm to it as a local PHP interpreter, it doesn’t recognize it as a valid PHP executable.

So what’s a good way to get this working?

How to&Answers:

With PhpStorm now having better integration with Docker engine (including Docker for Mac), you can now just do the following (or read this article):

Command line:

  1. Pull the phpunit Docker image: docker pull phpunit/phpunit
  2. (Mac and maybe Windows) Bridge the Docker socket to the API_URL: socat -d TCP-LISTEN:2376,range=,reuseaddr,fork UNIX:/var/run/docker.sock

Then Phpstorm:

  1. Configure connection to Docker engine:
    • Go to Settings -> Build, Execution, Deployment -> Docker
    • Create a new Docker configuration with API URL set to:
      • Linux: unix:///var/run/docker.sock
      • Windows and Mac: or tcp://localhost:2376
  2. Configure the remote interpreter:
    • Go to Settings -> Languages & Frameworks -> PHP
    • Create a new PHP CLI interpreter by:
      • Clicking on ... then + and ‘Remote…’
      • Select Docker with:
        • ServerImage:
        • Image name: phpunit/phpunit:latest
        • PHP executable: php
  3. Configure Phpunit:
    • Go to Settings -> Languages & Frameworks -> PHP -> PHPUnit
    • Create new Phpunit configuration (+ then ‘By Remote interpreter…’ and select
    • Set Use Composer Autoloader
    • Path to script: /opt/project/vendor/autoload.php
    • Default configuration file: /opt/project/phpunit.xml.dist
  4. Try to run your tests!


This works:

DIR=$(dirname $(readlink -f "$0"))
docker run --rm --sig-proxy=true -v ${DIR}:${DIR} -w ${DIR} --pid=host php:cli php "[email protected]"

just put it in some file, chmod +x it => just tested with idea and is recognized just fine 🙂

The trick to get all of phpstorms helper scripts to work really is to mount the directory the php executable resides in.
In case this script is not in the folder of your phpunit executable and source code you will have to extend it to also mount those.

(important side note here: they must be mounted to the same folder in container and host obv 🙂 )

Edit after a few months now, but maybe helpful to some:
Worked this out with a WordPress example here:


I know you say you heard ssh in docker containers is bad, but I think since PhpStorm doesn’t support docker’s exec to remotely run scripts it’s not a bad option. You can set up a docker container as a remote php interpreter using SSH inside PhpStorm, then just set up a remote PHPUnit configuration.

You can see step-by-step guide here:

Update: you don’t need to use SSH anymore. PhpStorm now supports docker, you can run PHP unit tests just by using a PHP docker image with PHPUnit installed as a remote interpreter.