Published on

Fully integrate DDEV and PhpStorm – including Unit Tests with Coverage

Authors

As I’m using DDEV for most of my projects (local Docker environment) and PhpStorm as IDE, I wanted to run tests directly from PhpStorm – not only via scripts, but fully integrated with coverage and the debugger.

Prerequisites

  • DDEV project set up and running
  • PhpStorm 2020.3+ (works with older versions too)
  • Xdebug installed in the DDEV image (standard for DDEV)

1) Configure the PHP interpreter (Docker/DDEV)

In PhpStorm:

  • Settings → PHP → CLI Interpreter → + → From Docker
  • Choose “Docker” (or “Docker for Mac/Windows”) and select the PHP container used by DDEV (e.g. "project"-web)
  • Name it e.g. “DDEV PHP”

Configure path mappings so the IDE knows how local paths map into the container, e.g.:

  • Local project root → /var/www/html (default DDEV docroot parent)

2) Xdebug setup

In the project:

  • Turn on Xdebug when needed: ddev xdebug on (and ddev xdebug off afterwards to avoid slowdown)

In PhpStorm:

  • Settings → PHP → Debug → Check that the Debug port matches Xdebug 3 default (9003)
  • Enable “Listen for PHP Debug connections”
  • Optionally set “Break at first line in PHP scripts” during initial setup

If you need step debugging for HTTP requests, configure a server under Settings → PHP → Servers:

  • Name: ddev
  • Host: "your-ddev-domain" (e.g. mysite.ddev.site)
  • Port: 80/443
  • Check “Use path mappings” and map local → remote paths

3) PHPUnit inside DDEV with coverage

Create or reuse a phpunit.xml(.dist) in your project and run PHPUnit inside the DDEV container.

Two common coverage options:

  • Xdebug (most flexible): enable via ddev xdebug on
  • phpdbg (fast coverage without Xdebug):
phpdbg -qrr ./vendor/bin/phpunit --configuration phpunit.xml --coverage-html build/coverage

In PhpStorm:

  • Settings → PHP → Test Frameworks
  • Add PHPUnit by Remote Interpreter → select the “DDEV PHP” interpreter
  • Composer autoloader: point to vendor/autoload.php
  • Default configuration file: phpunit.xml (or .dist)

Now you can Run/Debug PHPUnit from the IDE and view coverage reports.

4) Composer and quality tools inside the container

Use the remote interpreter for Composer and tools so everything runs in the same environment as DDEV:

  • Settings → PHP → Quality Tools (PHP_CodeSniffer, PHP CS Fixer, PHPStan/Psalm)
  • Point executables to container paths (or use Composer scripts)

Example Composer scripts:

{
  "scripts": {
    "test": "phpunit",
    "cs": "phpcs --standard=phpcs.xml src",
    "stan": "phpstan analyse -c phpstan.neon"
  }
}

Run via:

ddev composer test
ddev composer stan
ddev composer cs

5) Tips and troubleshooting

  • Ensure path mappings are correct; most debugging issues come from mismatches
  • With WSL2/Windows, confirm PhpStorm listens on IPv4 for Xdebug (see my separate Xdebug WSL2 note)
  • Disable Xdebug when not needed (ddev xdebug off) for performance

That’s it – PhpStorm now orchestrates execution inside DDEV: unit tests (with coverage), debugging, and quality tools, all from the IDE.