Configure Xdebug on Docker & PHPStorm

Let’s assume you installed XDebug on Docker via a Dockerfile that looks something like this:

# Base image: https://github.com/docker-library/php/blob/master/8.4/bookworm/fpm/Dockerfile
ARG PHP_VERSION=8.4

FROM php:${PHP_VERSION}-fpm

# Install Nginx and other system dependencies
RUN apt-get update && apt-get install -y \
    git \
    lsof \
    man \
    nginx \
    sudo \
    supervisor \
    libzip-dev \
    vim \
    procps \
    # We use the mysqldump tool provided by default mysql-client to create \
    # database backups as part of BackupDatabaseCommand.php
    default-mysql-client

# Install & enable PHP extensions
RUN docker-php-ext-install \
    pdo_mysql \
    zip \
  && pecl install xdebug \
  && docker-php-ext-enable xdebug

# Setup PHP
RUN echo "memory_limit=256M" > /usr/local/etc/php/conf.d/memory.ini

# Copy the default nginx.conf provided by the base image just for reference
RUN cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.orig

# Copy the custom nginx.conf to the container running Nginx
COPY docker/nginx.conf /etc/nginx/nginx.conf

# Copy the custom supervisord.conf to the container running Supervisor
COPY docker/supervisord.conf /etc/supervisor/conf.d/supervisord.conf

# Install composer
COPY --from=composer:latest /usr/bin/composer /usr/local/bin/composer

# Setup permissions
RUN chown -R www-data:www-data /var/www/html

# Copy php-fpm config file
COPY docker/php-fpm.conf /usr/local/etc/php-fpm.conf

# Copy xdebug config gile
COPY docker/xdebug.ini /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

EXPOSE 8080

RUN git config --global --add safe.directory /var/www/html

CMD ["/usr/bin/supervisord"]

You might need to change the below line:

# Copy xdebug config file
COPY docker/xdebug.ini /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

So that the destination folder (/usr/local/etc/php/conf.d in the example above) is another directory where your PHP installation scans for .ini files. You can run php --ini inside your Docker container to find out which directories PHP will scan.

Create .ini configuration file

In the Dockerfile above, we have this line:

# Copy xdebug config file
COPY docker/xdebug.ini /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

So create the docker/xdebug.ini file with the following contents:

zend_extension=xdebug
xdebug.mode=debug
xdebug.client_host=host.docker.internal

Restart and rebuild related Docker services

Restart and rebuild the image of whichever Docker service that you have PHP installed on. If using Docker Compose, run:

docker compose down && docker compose up -d --build

Verify XDebug is loaded

Add a /debug/xdebug route to your app that invokes xdebug_info(). When you access that route, you should see information about XDebug.

Configure PHPStorm

Test breakpoint got triggered

Add a breakpoint somewhere in a route, visit the route, and verify the breakpoint got triggered within PHPStorm.

Links

• Installation – XDebug docs
• All settings – XDebug docs
• Exclude other scripts from debugging in PhpStorm