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:
- Install an SSH server on our DDEV web container
- Make the SSH server accessible from the host
- Allow authentication with our private key
- Add PHP over SSH as Remote Interpreter in PHPStorm
- 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
Next I added a post-start hook to start the SSH server when starting DDEV in
hooks: post-start: - 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" services: web: ports: - "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:
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 [folder] - .homeadditions [folder] -- .ssh [folder] --- authorized_keys [file]
Then add your public key to the
Tip 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):
hooks: post-start: - 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.
- Open PHPStorm
- Go to Settings > Languages & Frameworks > PHP
- Click the tripe dot
...next to CLI interpreters
- Click the
+sign and choose the
From Docker, Vagrant, Vm, WSL, Remoteoption
SSHand configure the SSH connection
- 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:
- Go to Settings > Languages & Frameworks > PHP > Testing Frameworks
- Choose the SSH PHP interpreter we created in the previous step as CLI Interpreter
- Set up path mappings to allow PHPStorm to find the files
- Load phpunit via composer autoloader - the file dialog should already display the remote file system
- Add a configuration file if necessary
All done, you are ready to run tests directly in PHPStorm.
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.xmlconfig file and choose
- Open a test file and run the file or a single test by clicking the green arrow icon
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:
- Go to Settings > Languages & Frameworks > PHP > Composer
- Choose the remote SSH Cli Interpreter
- Set up the path mappings
composeras 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.
That's it for today, if you have any feedback, don't hesitate to contact me via Twitter (@sasunegomo) or TYPO3 Slack (@susi).