Fully integrate DDEV and PHPStorm - including Unit Tests with Coverage

2021 Updated post available!
While this way still works, I have found a better way - see my new blog post about it.

What I wanted to achieve

As I am using DDEV for most of my projects as simple docker environment for web development and PHPStorm as IDE I wanted to be able to run test from PHPStorm - not only as a script, but fully integrated with coverage and test debugging. Basically, what I wanted to achieve is what you see on the screenshot:


PHPStorm has a pretty good docker integration if we are talking about docker run or docker-compose run. That means, with the PHPStorm docker integration, you can use a docker image to run your tests, however you cannot connect to an existing, running docker container and use that to run your scripts. With DDEV, that is what we would need: We have DDEV running and now want PHPStorm to execute our tests in the DDEV environment.


While we cannot use PHPStorms docker integration, what we can use is the SSH integration. PHPStorm also offers the option to add a remote interpreter over SSH. This gave me a starting point, so what we need to do to get it running is:

  1. Install an SSH server on our DDEV web container
  2. Make the SSH server accessible from the host
  3. Allow authentication with our private key
  4. Add PHP over SSH as Remote Interpreter in PHPStorm
  5. Add PHPUnit by Remote Interpreter

Let's take a look - step by step:

Install an SSH Server in DDEV

First of all, I added the ssh package to the DDEV web image by adding the following line in DDEV's config.yaml:

webimage_extra_packages: [ssh]

Next I added a post-start hook to start the SSH server when starting DDEV in config.yaml:

    - exec: "sudo service ssh start"

When starting DDEV for the first time after adding this, the container image will be rebuilt with the SSH package and the SSH server will be started.

Make the SSH server accessible from the host

To allow connecting to the DDEV SSH server via the host from all platforms we need to forward the SSH port to the host. To do that, I added a file docker-compose.overwrite.yaml in the .DDEV folder with the following content:

version: "3.6"

      - "9922:22"

This config makes our DDEV SSH server accessible via port 9922 from the host (can be used with our DDEV site name as host - in my case: site-shop.DDEV.site:9922).

When using Linux based host systems (not Mac, not Windows, not WSL) you can directly access the SSH server via the container IP.
On systems using a virtualization layer in between (Windows/Mac) the IPs cannot be directly accessed - the port solution works around that limitation and allows us to use a more speaking name, too :)

Allow Authentication with our private key

As we mostly have an SSH agent running for all the things we do anyway, we should access our DDEV SSH server with that key, too, instead of using password based authentication. To achieve that, we need to add our public key to the server's authorized_keys file. DDEV has a feature called homeadditions which allows us to add files to our config that will be mounted in the home dir of our DDEV instance. That's perfect. Add the following structure in the folder .ddev/homeadditions:

.ddev [folder]
- .homeadditions [folder]
-- .ssh [folder]
--- authorized_keys [file]

Then add your public key to the authorized_keys file.

If you are using DDEV > 1.15 you can add your authorized_keys file to your global home additions. See https://ddev.readthedocs.io/en/stable/users/extend/in-container-configuration/
Otherwise, add the authorized_keys file to the .gitignore - especially if you are working on your projects with multiple people. That way you all can have your keys set up locally.

To ensure the file rights on the key are corrected, I extended my post-start hooks with a chmod command (replace the username with your username):

    - exec: "sudo chmod 600 /home/susan/.ssh/authorized_keys"
    - exec: "sudo service ssh start"

After restarting DDEV you should now be able to connect to your DDEV SSH server with your key. Try it:

ssh <your-username>@<your-sitename>.ddev.site -p 9922

Add PHP over SSH as Remote Interpreter in PHPStorm

Now that our SSH server is running, we need to configure our PHPStorm to run PHP via SSH.

  1. Open PHPStorm
  2. Go to Settings > Languages & Frameworks > PHP
  3. Click the tripe dot ... next to CLI interpreters
  4. Click the + sign and choose the From Docker, Vagrant, Vm, WSL, Remote option
  5. Choose SSH and configure the SSH connection
  6. Save all settings

With this config it's already possible to run all PHP script related things in PHPStorm in the DDEV environment.

Add PHPUnit by Remote Interpreter

As a last step to get our PHPUnit tests running via SSH we need to add a PHPUnit configuration - in PHPStorm:

  1. Go to Settings > Languages & Frameworks > PHP > Testing Frameworks
  2. Choose the SSH PHP interpreter we created in the previous step as CLI Interpreter
  3. Set up path mappings to allow PHPStorm to find the files
  4. Load phpunit via composer autoloader - the file dialog should already display the remote file system
  5. Add a configuration file if necessary

All done, you are ready to run tests directly in PHPStorm.

Run Tests

After completing the setup you can now run tests in PHPStorm. If everything is set up correctly you can for example:

  • Right click a phpunit.xml config file and choose Run
  • Open a test file and run the file or a single test by clicking the green arrow icon

Debugging Tests

If you want to debug tests or run the tests with coverage, you need to enable xdebug first:

ddev xdebug on

after that, you can use the bug icon in PHPStorm to run the tests with a debugger available.

Bonus: Run composer scripts via ddev

In some projects we are making heavy use of composer scripts as shortcuts for running tests, cgl fixer, PHPStan etc. With the setup we have now, it's easy to also run these scripts via our ddev interpreter. The configuration is similar to the PHPUnit configuration:

  1. Go to Settings > Languages & Frameworks > PHP > Composer
  2. Choose the remote SSH Cli Interpreter
  3. Set up the path mappings
  4. Add composer as composer executable

As a result you will now get the "little green arrow" in the composer.json file, allowing you to run the scripts in PHPStorm on your DDEV environment with a single click.

Feedback welcome
That's it for now, if you have any feedback, don't hesitate to contact me via Twitter (@sasunegomo) or TYPO3 Slack (@susi).