Skip to content

Instantly share code, notes, and snippets.

Last active September 1, 2023 12:43
Show Gist options
  • Save chadrien/c90927ec2d160ffea9c4 to your computer and use it in GitHub Desktop.
Save chadrien/c90927ec2d160ffea9c4 to your computer and use it in GitHub Desktop.
Debug PHP in Docker with PHPStorm and Xdebug

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" > /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
  1. Get you local IP address (ifconfig or such)
  2. 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
      build: path/to/Dockerfile
        XDEBUG_CONFIG: remote_host={{YOUR_IP_ADDRESS}}
  1. 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!

Copy link

bedger commented Apr 22, 2020

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 to any port 9000 comment xdebug

You can check this discussion for more information

Copy link

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

The main change to the xdebug.ini file is:


xdebug.mode = debug

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment