Debugging Web Applications In PHPStorm With Xdebug And Docker

Overview

How to debug a PHP web application in PHPStorm using Docker and XDebug.

PHP configuration

Docker server

Preferences > Language & Frameworks > PHP > Servers

Click the "plus" icon to create a new server.

• Name: docker
• Host: localhost
• Port: 80
• Debugger: Xdebug
• Use path mappings: checked

Then under path mappings create associations between project files and their respective locations in the Docker container, e.g.:

The host and port reference host and port within the Docker container. This applies to the path mappings as well.

The container's HTML root is /var/www/html. This path may or may not exist on the local file system, but that doesn't impact anything here.

Two project file directories cannot point to the same path on the server (e.g. bfhhand_web and common_lib can't coexist in the same root directory as they do on production.)

Run configuration

Run > Edit Configurations...

Click the "plus" icon to create a new Debug Configuration.

Select PHP Remote Debug

• Name: docker
• Server: docker-server
• IDE key: docker

docker-server is the server that was created in the previous step.

The value of the IDE Key must match the value that is put into the xdebug.ini file that is created later in the process.

Xdebug preferences

These are the defaults, they can be confirmed, but don't need to be changed

Preferences > Languages & Frameworks > PHP > Debug > Xdebug

• Debug port: 9000
• Can accept external connections: checked

Docker container configuration

Dockerfile

The following files are placed in the PHPStorm project directory. They should not be uploaded to production.

FROM php:7.2

RUN yes | pecl install xdebug \
    && docker-php-ext-enable xdebug

COPY xdebug.ini /usr/local/etc/php/7.2/conf.d/

COPY start-container /usr/local/bin/start-container
RUN chmod +x /usr/local/bin/start-container

EXPOSE "80"

CMD ["start-container"]

• Installs xdebug
• Applies local xdebug.ini to the container.
• Makes start-container script available to the container.
• Makes http port 80 available in the container.
• Runs the start-container script.

xdebug.ini

zend.extension = xdebug.so
xdebug.remote_enable = 1
xdebug.remote_handler = "dbgp"
xdebug.remote_port = 9000
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 0
xdebug.idekey="docker"
xdebug.remote_host = 10.254.254.254
xdebug.remote_log="/tmp/xdebug.log"

• xdebug.idekey refers back to the IDE key entered in PHPStorm's run configuration.
• xdebug.remote_host could be the IP address of the local machine, but this would have to be changed any time the IP address changes. See below for the work-around that explains the setting above.
  • In a Mac OS terminal find the current IP with ipconfig getifaddr en0
• xdebug.remote_connect_back must be set to "0" or else it would override the xdebug.remote_host settting.
• xdebug.remote_port must be the same as PHPStorm > Preferences > Languages & Frameworks > PHP > Debug > Xdebug > Debug Port.

start-container script

Create a bash script in the project directory named start-container (to match the directive in the Dockerfile).

#!/usr/bin/env bash

php -S 0.0.0.0:80 -t /var/www/html

This starts a PHP server listening at all addresses on port 80.

Its root directory is /var/www/html which matches the paths set in PHPStorm > Preferences > Language & Frameworks > PHP > Servers > docker > path mappings.