Debug PHP in Docker with PHPStorm and Xdebug

README.md

Debug your PHP in Docker with Intellij/PHPStorm and Xdebug

1. For your local dev, create a Dockerfile that is based on your production image and simply install xdebug into it. Exemple:

FROM php:5

RUN yes | pecl install xdebug \
    && echo "zend_extension=$(find /usr/local/lib/php/extensions/ -name xdebug.so)" > /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_enable=on" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_autostart=off" >> /usr/local/etc/php/conf.d/xdebug.ini

2. Get you local IP address (ip -o -4 addr list ${MY_NETWORK_INTERFACE:-eth0} | awk '{print $4}' | cut -d/ -f1)
3. Start your container with the following environment variables: XDEBUG_CONFIG="remote_host={{YOUR_IP_ADDRESS}}"

• Simple docker run: docker run -e XDEBUG_CONFIG="remote_host={{YOUR_IP_ADDRESS}}" your-image

• With docker-compose:

  # docker-compose.yml
  foo:
    build: path/to/Dockerfile
    environment:
      XDEBUG_CONFIG: "remote_host={{YOUR_IP_ADDRESS}}"
      PHP_IDE_CONFIG: "serverName=my.local"

4. In Intellij/PHPStorm go to: Languages & Frameworks > PHP > Servers > and set the following settings:

• Name: name of your server, should be equal to value in PHP_IDE_CONFIG variable

Then you're all set and can start listening for PHP Debug connections from your IDE.

Happy debugging!

Actually the solution is extremely simple now: Just set remote_host to the new special DNS name host.docker.internal. For example:

xdebug.remote_host = host.docker.internal

This now works with Docker for Windows or Docker for Mac (not Docker Toolbox) starting from version 18.03 and later. I just tried it and it worked perfectly for me. See documentation: Windows and Mac.

The nice thing about this elegant solution is that it fully abstracts away the magic behind the scenes associated with figuring out the IP address of your host development machine. IMHO, it should be Docker's responsibility to figure that out for you anyway, not the other way around.

EDIT: I've created my own Gist outlining this in detail from scratch here: https://gist.github.com/patricknelson/57ae24986cb13613314fb1f3c00a95d7

@mbaric answer made it work for us. Thank you for helping us!

No problem @jmossetc. Glad I could help.

Was it working for you guys because of the manual binding in the compose configuration to the environment variable XDEBUG_CONFIG="remote_host=172.19.0.9"? What happens when you change that IP to host.docker.internal?

If it works, I think it can be dramatically simplified by just hard-coding that hostname (either host.docker.internal or using10.0.2.2 if you're using Docker Toolbox with Virtualbox). The full hard-coded XDebug INI configuration can be found in my gist (also linked above) which doesn't need to be modified in environment variables, hopefully centralizing and de-cluttering things a bit.

@patricknelson my remote_host parameter is set to docker.host

I had trouble configuring xdebug. According to an old issue, you need to remove double quotes from the environment variable as follow

PHP_IDE_CONFIG="serverName=myserve"
changed to
PHP_IDE_CONFIG=serverName=myserver

And that made it work.