Follow these steps to get xDebug working on a Docker container.

1. Modify xdebug.ini file

To setup xDebug parameters having a xdebug.ini file injected to the Docker file, it’s an easy way.

First, we need to tell xDebug which is our local IP so the container knows where has to send xDebug data:

xdebug.remote_host = <LOCAL_IP>

Sometimes on Mac OS a local IP could not work so we could try with an alias:

sudo ifconfig en0 alias 10.254.254.254 255.255.255.0

In the following steps we’ll use the alias instead of the local IP.

Build your container so get the last changes applied.

2. Modify xdebug.env file

Set a server name that will match with our PHPStorm configuration in the next step:

PHP_IDE_CONFIG=serverName=<SERVER_NAME>

3. PHPStorm configuration

  • Go to Preferences > Languages & Frameworks > PHP > Servers
  • Add a new server with the same name as PHP_IDE_CONFIG=serverName= value, for example phpserver
  • Host:
    • 10.254.254.254 if you use the alias commented above
    • 127.0.0.1 if you use native Docker
    • If you are using Docker Machinge or Dinghy get the ip of the VM where it’s running
  • Port: <EXPOSED_PORT> -> 80 port mapped inside php container
  • Debugger: xDebug
  • Check: Use path mappings to map local machine path with the inside ones in the container
  • Set root folder as /var/www

4. Set a breakpoint

Open PHPStorm and set a breakpoint on index.php or any PHP file.

5. Start debugging mode

Click the phone button to start listening connections.

6. Execute the PHP file

Access through the browser or execute the PHP file.

7. Pop up

A pop up will appear and you should set the mapping to docker’s root /var/www.