Debugging PHP in a Docker container with PhpStorm

Getting debugging to work with PHP running inside a Docker container can be a hassle. This post is a step-by-step guide on setting up debugging PHP in a Docker container with PHPStorm. This guide works for any PHP framework and library, no matter if your project is running vanilla PHP, CodeIgniter or another setup. You can find a working example project here [1].

To debug your PHP project with PhpStorm, follow these steps:

Create a directory docker with the files error_reporting.ini and xdebug.ini.
- Directorydocker
  - error_reporting.ini
  - xdebug.ini
- Directorysrc
  - […]
- Dockerfile
- docker-compose.yaml
- […]
error_reporting.ini
```
error_reporting=E_ALL
```
xdebug.ini
```
zend_extension=xdebug

[xdebug]
xdebug.mode=develop,debug
xdebug.client_host=host.docker.internal
xdebug.start_with_request=yes
```

Mount the two config files you just created into the Docker container by modifying your docker-compose.yaml file.

Your compose file my look different of course. The important thing is to add the three lines indicated just below.

services:
    apache:
        build: .
        ports:
            - "80:80"
        volumes:
            - ./docker/xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
            - ./docker/error_reporting.ini:/usr/local/etc/php/conf.d/error_reporting.ini

Make your host IP address available inside the container via host.docker.internal by further modifying your docker-compose.yaml file.

services:
    apache:
        build: .
        ports:
            - "80:80"
        volumes:
            - ./docker/xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
            - ./docker/error_reporting.ini:/usr/local/etc/php/conf.d/error_reporting.ini
        extra_hosts:
            host.docker.internal: host-gateway

Install and enable xdebug in the Docker container by adding the following RUN instruction to your Dockerfile.

Your Dockerfile may look different of course. The important thing is just to add RUN pecl install xdebug && docker-php-ext-enable xdebug.
Dockerfile
```
FROM php:apache

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

WORKDIR /var/www/html

COPY src .

CMD ["apache2-foreground"]
```
Make sure PhpStorm debug settings are configured correctly.
Configure path mappings between PhpStorm and the Docker container.
Create a PhpStorm PHP Remote Debug configuration.
Run the PhpStorm PHP Remote Debug configuration and make sure PhpStorm is listening for incoming connection.
Install an Xdebug browser addon, configure the IDE key and enable debugging.

Refer to this table by JetBrains. For this guide, I will use Firefox and Xdebug Helper.
Set a breakpoint and enjoy your debugging experience!

Debugging PHP in a Docker container with PhpStorm

References