В дополнение к https://blog.rvalitov.ru/development/php/xdebug-docker-phpstorm настройка Php 8 Xdebug 3 в докер и PhpStorm

В целом вся настройка не отличается от настройки в статье, за исключением некоторых вещей:

1. в env необходимого билда (образа) необьходимо прокинуть:

 environment:
        PHP_IDE_CONFIG: "serverName=Docker"

2. в образе с php (для php8 alpine) установить xdebug-3

   RUN apk add --no-cache $PHPIZE_DEPS \
   && pecl install xdebug-3.0 \
   && docker-php-ext-enable xdebug

3. поправить конфиги php.ini

   [xdebug]
   zend_extension=xdebug.so
   xdebug.mode=debug
   xdebug.client_host=172.17.0.1 ; для macOS должно работать host.docker.internal
   xdebug.start_with_request=yes

   при этом 172.17.0.1 — по-умолчанию для linux, для MacOS — host.docker.internal

этот файл можно прокинуть в папку с конфигами php например через volume

- ./api/docker/php/local.ini:/usr/local/etc/php/conf.d/local.ini

4. Настроить Debug в PHPStorm
   Settings > PHP > Servers:
   Name: Docker
   Host: _
   Use path mapping: true (checkbox)
   Далее необходимо указать маппинг — соответствие директории на сервере (в докере) и локальной

Settings > PHP:
CLI Interpreter > …
Server: Docker (созданный на предыдущем шаге)
Configuration files: ./docker-compose.yml
Service: api-php-cli
Environment variables: APP_DEBUG=1 (переменные окружения можно добавлять не только тут)

в разделе General должны быть указаны версии PHP и Xdebug

5. Подключение тестов в докер в PhpStorm (PHPUnit)
   Settings > PHP > Test Frameworks:
   CLI Interpreter: api-php-cli (добавленный на предыдущих шагах)
   Use composer autoload — указать путь до autoload.php (внутри докера) (например /var/www/api/vendor/autoload.php)
   Если все успешно добавлено и внутри контейнера получилось добраться до phpunit, то будет указана его версия.
   Так же можно указать конфигурационный файл для phpunit в Default configuration file (тоже относительно образа докера) (например /var/www/api/phpunit.xml.dist)

в разделе Run/Debug configuration добавить конфигурацию для запуска тестов PHPUnit и указать папку, в которой лежат тесты для запуска.

Если установлены XDebug, то PHPStorm на основе PHPUnit может запускать тесты с покрытием.

Возможные ошибки:

Cannot load Xdebug — it was already loaded

говорит о том, что Xdebug пытается загрузить второй раз. Для решения можно попробовать удалить (или закомментировать) строчку в local.ini —
zend_extension=xdebug.so. Связано это с тем, что docker-php-ext-install уже добавил необходимое значение, а значит тут этого делать уже не нужно.

Ошибка при запуске composer … внутри контейнера вызывает debug панель с ошибкой Remote file path ‘/bin/composer’ is not mapped to any file path in project

необходимо отключить прерывание при ошибке маппинга
Settings > PHP > Debug:
Xdebug:

• Force break at first line when no path mapping specified (отключить)

Источники

• PHP: Настраиваем отладку. PhpStorm + PHP 8 + Docker + Xdebug 3
• How do I install XDebug on docker’s official php-fpm-alpine image? — Stack Overflow
• PHPStorm + Xdebug + Alpine on Docker — DEV Community
• Running PHPUnit Tests in PhpStorm with Docker
• php — PHP7 CLI attempts to load xdebug twice — "Cannot load Xdebug — it was already loaded" — Stack Overflow
• testing — Running PHPUnit test from CLI and debug in PhpStorm: Remote file path ‘/directory/path/-‘ is not mapped to any file in project — Drupal Answers