Xdebug with Docker Compose and PHPStorm

In this section you read about how to set up and use Xdebug (v3) in PHP projects with PHPStorm and Docker Compose. This guide uses a PHP image with version 7.4. PHP versions from 7.2 to 7.3 might also work, but have not been examined.

Install Xdebug

Either you already have a Dockerfile that defines your PHP image or you have to create a new one.

Existing Dockerfile

Add the following content to your Dockerfile:

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

New Dockerfile

If you do not have a Dockerfile for your PHP image, you can create one by inheriting from the used PHP image in your docker-compose.yml. Just add the RUN statement above.

Example for new Dockerfile

If this is your PHP service in the docker-compose.yml:

docker-compose.yml:

version: "3.7"

services:
  php:
    image: ambimax/php-7.4-buster
    volumes:
      - ./:/var/www:delegated

This could be your new Dockerfile:

Dockerfile:

FROM ambimax/php-7.4-buster

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

Configure Xdebug

To configure Xdebug for this environment you need to place the following file to /usr/local/etc/php/conf.d/xdebug.ini in your PHP image/container:

xdebug.ini:

xdebug.mode=debug
xdebug.discover_client_host=0
xdebug.client_host=docker.for.mac.localhost
xdebug.client_port=9003

Either you do it in the Dockerfile via COPY or in the docker-compose.yml via the volumes specification:

Dockerfile:

COPY docker/fpm/assets/conf.d/xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

docker-compose.yml:

version: "3.7"

services:
  php:
    image: ambimax/php-7.4-buster
    volumes:
      - ./:/var/www:delegated
      - ./docker/fpm/assets/conf.d/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini

Verify installation

After you have re-build the new image with docker compose build php (php is the name of the PHP service in the docker-compose.yml) you can verify if Xdebug is installed by running the following command in your PHP container:

php --version

The output should list Xdebug among the installed extensions.

Configure PHP Container

Adjust the environment specification of your PHP service in the docker-compose.yml like the following:

version: "3.7"

services:
  php:
    image: ambimax/php-7.4-buster
    volumes:
      - ./:/var/www:delegated
      - ./docker/fpm/assets/conf.d/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini
    environment:
      - PHP_IDE_CONFIG=serverName=Xdebug
      - XDEBUG_SESSION=PHPSTORM

XDEBUG_SESSION=PHPSTORM lets PHPStorm know, you want to establish a connection
PHP_IDE_CONFIG=serverName=Xdebug relates to the PHPStorm PHP server called "Xdebug" you will create in the next section

Notes

Additional Xdebug configuration

You can set additional Xdebug configuration in your PHP service through the ENV XDEBUG_CONFIG:

    ...
    environment:
      ...
      - XDEBUG_CONFIG=idekey=PHPSTORM # e. g. instead of using XDEBUG_SESSION=PHPSTORM

More convenient CLI usage

To use the Xdebug extension only if intended, turn it off through the ENV XDEBUG_MODE:

    ...
    environment:
      ...
      - XDEBUG_MODE=off

Use it explicitly: XDEBUG_MODE=debug php ./script-with-breakpoint.php

Configure PHPStorm

In this section you only need to create a PHPStorm server.

Create PHPStorm server

Go to your PHPStorm settings with CMD + , and navigate to PHP -> Servers. Create a server like in the screenshot below. Note, that you have to set the correct path mapping:

PHPStorm Server Configuration

Press "Apply" and "OK".

Usage

Everything should be set to use Xdebug. Start listening for debug connections by clicking this icon in the top right corner of PHPStorm:

Start Listening For Debug Connection

Now start debugging by using breakpoints and execute your commands or visit the respective page via browser. To stop listening for debug connections, click the icon again.

Developer Guide