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 might 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.

These settings should be correctly configured by default. Just to be sure, check them anyway. You can find them under File → Settings → PHP → Debug. Make especially sure that the Xdebug ports are not changed from 9000 and 9003.

The Xdebug ports should be set to 9000 and 9003 by default.
Configure path mappings between PhpStorm and the Docker container.

Here you have to set the path of you source files as they will be inside the Docker container. The exact configuration will depend on your setup. The below screenshot shows how the path mapping will have to be configured for the example project.

The src directory will be mapped to /var/www/html in the Docker container.
Create a PhpStorm PHP Remote Debug configuration.

Now create a run configuration for debugging PHP. Add a new configuration and choose “PHP Remote Debug” as the type. You won’t have to change any settings for the run configuration.

The PHP Remote Debug run configuration. No configuration is neccessary.
Run the PhpStorm PHP Remote Debug configuration, set a breakpoint and make sure PhpStorm is listening for incoming connection.

Select the run configuration you just created in the drop-down on the top left. Then press debug (the green bug icon).

PhpStorm will break on the selected line.
Install an Xdebug browser addon, configure the IDE key and enable debugging in the browser.

For Xdebug to activate, you have to send a special cookie with your requests. There are many browser extensions automating this process. Refer to this table by JetBrains. The following screenshot was created using Firefox and Xdebug helper.

With the browser extension enabled, Xdebug will activate.
Start the PHP Docker Server.

Now that everything is set up, you can start your PHP server running in the Docker container. If you use docker compose, simply run docker compose up --build --force-recreate. The two additional flags make sure changes are applied.
Set a breakpoint and enjoy your debugging experience!

Finally, set a breakpoint in PhpStorm and load the corresponding page using your configured browser!

PhpStorm will now break whenever the lines you set a breakpoint on are executed.

Debugging PHP in a Docker container with PhpStorm

References