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 (ifconfig or such)
3. Start your container with the following environment variable: 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}}

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

• Host: your IP address
• Port: 9000

Then you're all set and can start listening for PHP Debug connections from your IDE. On the first run it will ask you to map your local directoryies to the docker directories, but after that nothing will be required anymore!

Happy debugging!

If you have problems with running it on Linux (Ubuntu in my case) & you have a firewall enabled then the solution for you may be opening firewall ports for connection to port 9000 on docker service
sudo ufw enable && sudo ufw allow in from 172.16.0.0/12 to any port 9000 comment xdebug

You can check this discussion for more information

Here is a quick reference for XDebug 3 and Docker Gist.

The main change to the xdebug.ini file is:

[XDebug]
zend_extension=xdebug.so

xdebug.mode = debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal