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-server
• 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: 9001
• Can accept external connections: checked

Docker container configuration

The three files used in the Docker container configuration (Dockerfile, xdebug.ini, docker-compose.yml) are all located in the PHPStorm project root directory. These files should not be uploaded to production. The actual web files should be placed one directory down from the root, e.g. in a directory named app.

Dockerfile

FROM php:5.6-apache

RUN apt-get update &&\
    apt-get install --no-install-recommends --assume-yes --quiet ca-certificates curl git vim &&\
    rm -rf /var/lib/apt/lists/*

RUN pecl install redis-2.2.7 \
    && pecl install xdebug-2.5.5 \
    && docker-php-ext-install mbstring pdo pdo_mysql mysqli \
    && docker-php-ext-enable redis xdebug

RUN mkdir /var/log/httpd/
ENV APACHE_LOG_DIR /var/log/httpd

RUN a2enmod headers rewrite

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

EXPOSE "80"

The most important functions of this file are

• Pull a PHP image.
• Install Xdebug and MySql PHP extensions.
• Applies local xdebug.ini to the container.
• Makes http port 80 available in the container.

Other conveniences built into the file:

• Install curl, git, and vim in the container.
• Log server errors to accessible log file.
• Enable mod_rewrite directives and any non-default modules referenced in .htaccess.

xdebug.ini

zend.extension="/usr/local/lib/php/extensions/no-debug-non-zts-20170718/xdebug.so"
xdebug.remote_enable=1
xdebug.remote_handler="dbgp"
xdebug.remote_port=9001
xdebug.remote_autostart=1
xdebug.remote_connect_back=0
xdebug.idekey="docker"
xdebug.remote_host=docker.for.mac.localhost
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.
• If you're debugging more than one PHP web application, then you either remove all Docker images except the one for the current app, or make sure that they are using different ports.

docker-compose.yml

version: '2'
services:
  app:
    build:
      context: .
    image: xdebug-bfhhand:latest
    volumes:
      - ./:/var/www/html
      - ~/develop/bfhhand/keys:/var/www/keys
      - ~/develop/common_lib:/var/www/html/common_lib
    ports:
      - "80:80"

• The context directive specifies where the Dockerfile is located.
• image specifies the name of the Docker container that will be created.
• volumes maps local directories to directories in the Docker container. These mappings correspond to the mappings found in PHPStorm > Preferences > Language & Frameworks > PHP > Servers > docker > path mappings.
• ports maps the port used to reach the container with the port used inside the container.

Starting the Docker container

$ docker-compose build
$ docker-compose up -d
$ curl localhost

or simply

$ docker-compose up -d --build
$ curl localhost

The -d option is for "detached" to get the terminal prompt back after running the command.

The server is tested with curl localhost.

Stop the container with

$ docker-compose down

Remove the image with

$ docker rmi [IMAGE_NAME]

Connecting the the Docker container with PHPStorm

Run > Debug… > Select docker (PHP Remote…) from the dropdown options.

Or in the upper right corner select docker from the drop down and click the Debug icon.

It doesn't seem to be necessary to turn on Run > Start Listening for PHP Debug Connections, but it doesn't interfere either.

Then in a browser load http://localhost or in a terminal window enter curl localhost. The IDE will automatically catch the request and break at any breakpoints.

Any changes to the source files in PHPStorm are immediately available on the server. The volumes directive in docker-compose.yml creates the links between the local source directories and the server directories.

See also

External links

• Docker Cookbook
• Xdebug Extension for PHP documentation