Docker + xdebug, zero thinking, screenshot only, 5 minutes guide.

In collaboration with Luciano.

Dockerfile part for dev environment

mount xdebug.ini file from your project inside the container

xdebug.ini contents — port, idekey are used in PHPStorm settings

Important For the time of writing, this is valid for Windows or MacOS only, because of host.docker.internal and this issue.

However, a workaround exists for Linux users. Add extra_hosts setting to the docker-compose.override.yml like this:

using extra_hosts to enable debugging for docker environment

And execute the following command on the host machine:

export DOCKER_HOST_IP=$(ip route | grep docker0 | awk ‘{print $9}’)

This will make the hostname host.docker.internal resolvable to your host IP address. You can now restart the container and have the hostname resolvable to your host machine’s IP from inside the container.

Let’s continue with the configuration.

PHPStorm -> Preferences -> PHP -> xdebug, port is from xdebug.ini

Run/Debug Configurations -> PHP Remote Debug, IDE key is taken from xdebug.ini

PHPStorm ‘Server’ configuration: host (host.docker.internal) and path mappings of project root to /app (assuming /app is internal docker project root for you) are important, server name does not matter

Start listening and click ‘debug’, keep it in “waiting” mode forever

Install ‘Xdebug helper’ chrome extension and configure ‘IDEKEY’ value for IDE key there

open your dockerized site and activate debugging with the extension in Chrome

Done

Just enable/disable the debugging via Chrome extension, and keep the debug configuration always ON in PHPStorm. That’s it!! It works! 🧨

Xdebugging CLI scripts

Debugging dockerized CLI script is also possible, and everything is in place already if you did the previous steps. Just pass the proper configuration values as options of PHP when you run the script, and you are done:

php -dxdebug.remote_enable=1 -dxdebug.remote_autostart=1 -dxdebug.remote_host=”host.docker.internal” -dxdebug.idekey=IDEKEY -dxdebug.remote_port=9008 yourscript.php