A quick guide to how to do this, since I always forget and have to look it up. This is done with docker4drupal, but should work equally well with any Docker Compose setup.
Docker on Windows: Xdebug for PhpStorm ¶ Docker for Windows requires a well known IP address in order to connect to the host operating system. Xdebug: Windows + PhpStorm + Docker Desktop + CodeIgniter. I created a new CodeIgniter project and need to setup debugging with Xdebug against a container running in Docker Desktop. I'm not sure how to connect Xdebug to the container given my directory structure. I get an incoming connection dialog but not sure how to map it properly.
Enable xdebug on the relevant Docker container. For docker4drupal this means uncommenting these lines in the
docker-compose.yml
file:- PHPSTORM + XDEBUG (2/3) + WSL2 + DOCKER. Small example project to show how to configure xdebug (2 or 3) with WSL2 and Docker. This solution works only if you use PhpStorm on WSL2 with X server! WSL2 change Linux IP every reboot time, so you should, add global variable (WSLIP) in your Linux system.
- Instruct XDebug to connect back to the IP where web request came from. Instruct XDebug to connect to host.docker.internal for command line execution or whenever “connect back” is not possible. Set PHPIDECONFIG env variable to serverName=localhost. This will tell your PhpStorm which server configuration to use. See next step for details.
- # Configure PhpStorm PHPStorm acts as a debugging client. It accepts connections from xDebug extension and allows you to set breaking point, evaluate variables and other good stuff. First of all, you need to configure the xDebug.
If you enable these after you've created the PHP container, remember to restart the container so that xdebug is enabled and configured.
Now go to Settings > Languages & Frameworks > PHP and set your language level as required. Add a new CLI interpreter by clicking
...
. Click the +
on the top left and add a new Docker configuration. Select Docker Compose and the php service, then use the default options for everything else. Save this and apply.Next click the 'Add configuration' button on the taskbar in the top right. Pick the PHP Remote Debug template and click the
+
on the top left to add a new configuration (don't make the mistake of editing the template). Check 'Filter debug connection by IDE key' and set the IDE key to match the one in your XDebug config (for the above we'd use PHPSTORM
). Add a server (the name doesn't matter). Give it the appropriate host and port—for docker4drupal the host will be something like http://myproject.docker.drupal.localhost, and the port will be 8000 unless you've changed it. Check 'Use path mappings', and set a path mapping for the root directory to /var/www/html
(or wherever it's mounted to on the container).Phpstorm Xdebug Ssh
It's important to note that for this to work with Drush, or anything that exists both in Composer and globally, you need to invoke Drush from the binary in the vendor directory
vendor/bin/drush
rather than using the system Drush, so that PHPStorm can use the path mappings. You could do this with a make command or Composer script. A make command I've used in the past:This is a modified version of the default docker4drupal command.
ddev
The process for ddev is largely the same. You can skip the step for setting up the CLI interpreter as this will work fine without it. An important point is that the name of your debug configuration must match your ddev site domain for this to work. See the ddev documentation for more details.
XDebug 3 only started working out of the box with PhpStorm version 2020.3
Reference article - Configure Xdebug
The list of changes from XDebug 2 to 3 are available here for reference - Upgrade Guide
Configuring PhpStorm
Go to PhpStorm -> Settings -> Languages & Frameworks -> PHP -> Servers
- Click '+'
- Name
docker-cli
(Same as serverName under PHP_IDE_CONFIG environment variable) - Host
_
- Default 80
- Debugger Xdebug
- Check the checkbox next to 'Use path mappings'
- Modify the absolute path on the server to
/var/www/html
Running the CLI Command
- Add breakpoints file
- In PhpStorm click the icon to 'Start Listening for PHP Debug connections'
- Run in the docker file -
docker-compose run php-container php test.php
Troubleshooting
Phpstorm Xdebug Docker Cli
- Check firewall or selinux if on linux
- The configuration
host.docker.internal
only became available under Mac and Windows with Docker version20.04