В этом мануале мы создадим проект с настроенными xDebug, nginX и PHP-FPM. Все файлы отображенные ниже проще достать из репозитория.

Для быстрого старта склонируйте репозиторий с github'a:

git clone https://github.com/itreviewchannel/xdebug-docker-phpstorm.git .

и запустите docker-compose:

docker-compose up

Настройка браузера

Для работы отладчика желательно установить расширение для используемого браузера, чтобы вручную не прописывать GET-параметры для старта отладки. Его нужно активировать перед отладкой.

Xdebug helper для Google Chrome.

Xdebug Helper для Firefox.

В параметрах плагина укажите "IDE KEY" как "PHPStorm".

Настройка PHPStorm

Для использования xDebug версии 3 необходимо установить PHPStorm 2020.3 и новее, так как предыдущие версии с ним не работали.

В PHPStorm'e необходимо указать наименование тестового сервера, который указан в docker-compose.yml.

Остальные настройки по умолчанию указаны верно, но на всякий случай покажу свои для этого тестового проекта.

Пример настроек соединения PhpStorm'a с Docker'ом:

Настройка Docker

Исходники проекта

version: '3'

services:

  webserver:
    image: nginx
    volumes:
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf
      - ./:/var/www/html
    ports:
    - "80:80"
    depends_on:
      - php

  php:
    build:
      context: ./docker/php
    volumes:
      - ./:/var/www/html
      - ./docker/php/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini
    environment:
      - PHP_IDE_CONFIG=serverName=mytestservername

server {
    # Слушаем 80 порт.
    listen 80;

    # Указываем корневой каталог для запросов.
    root /var/www/html/public;

    # Указываем индексные файлы.
    index index.php index.html;

    # Определяем конфигурация для корня.
    location / {
        # Проверяем на существование файлы и используем для обработки если они найдены.
        try_files $uri $uri/ /index.php$args;
    }

    # Определяем конфигурацию для PHP-скриптов через регулярное выражение.
    location ~ \.php$ {
        # Парсим переменную $fastcgi_path_info для получения $fastcgi_script_name и $fastcgi_path_info.
        fastcgi_split_path_info ^(.+\.php)(/.*)$;

        # Указываем адрес FastCGI-сервера.
        fastcgi_pass php:9000;
        # Указываем индексный файл.
        fastcgi_index index.php;

        # Активируем настройку fastcgi_params.
        include fastcgi_params;

        # Указываем наименование скрипта.
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        # Указываем информацию об указанном пути (который в URL).
        fastcgi_param PATH_INFO $fastcgi_path_info;

        # Увеличиваем время ожидания ответа, по умолчанию оно равно 60 секундам.
        fastcgi_read_timeout 300;
    }
}

FROM php:fpm

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

[xdebug]
xdebug.mode = debug
xdebug.client_host  = host.docker.internal

Для Linux'a следует использовать IP сети из команды ifconfig.

Полезные ссылки

Репозиторий с примером (https://github.com/ITReviewChannel/xdebug-docker-phpstorm);
Upgrading from Xdebug 2 to 3 (https://xdebug.org/docs/upgrade_guide);
Documentation - all settings (https://xdebug.org/docs/all_settings);
Docker Hub - PHP (https://hub.docker.com/_/php?tab=description).