Як налаштувати Xdebug для Laravel у Docker і чому IDE не отримує з'єднання?

Question

Accepted Answer

Xdebug - налагоджувач PHP: точки зупинки, покрокове виконання, перегляд змінних. У Docker головна складність - мережева: Xdebug сам ініціює з'єднання з IDE (порт 9003), а IDE працює на хості, поза контейнером.
Мінімальна конфігурація PHP у контейнері:
[xdebug]
xdebug.mode=debug,develop
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.start_with_request=trigger   ; лише за запитом, а не на кожен

host.docker.internal - ім'я, що вказує на хост із контейнера. На Docker Desktop (macOS, Windows) воно працює автоматично; на Linux його треба додати явно:
services:
  app:
    extra_hosts:
      - "host.docker.internal:host-gateway"

У Laravel Sail це вже налаштовано: досить змінної в .env - SAIL_XDEBUG_MODE=develop,debug,coverage - і перезапуску контейнерів. Для CLI-команд - sail debug artisan ....
Налаштування IDE (PhpStorm):

слухати вхідні з'єднання налагодження на порту 9003;
відображення шляхів (path mappings): код у контейнері лежить у /var/www/html, а на хості - у ~/projects/app. Без відображення IDE отримує з'єднання, але не може зіставити файли й не зупиняється на точках;
ім'я сервера (PHP_IDE_CONFIG=serverName=...) збігається з налаштуваннями сервера в IDE.

Чому з'єднання не приходить - чек-лист:

Xdebug не ввімкнено: php -v у контейнері має показувати Xdebug, php -i | grep xdebug.mode;
немає тригера при start_with_request=trigger - потрібне розширення браузера Xdebug Helper чи параметр XDEBUG_TRIGGER;
неправильний client_host - особливо на Linux без host-gateway;
фаєрвол хоста блокує вхідний порт 9003;
IDE не слухає чи слухає інший порт (старий Xdebug 2 використовував 9000);
журнал Xdebug показує причину: xdebug.log=/tmp/xdebug.log - там видно спробу з'єднання і помилку.

Продуктивність: Xdebug помітно сповільнює PHP навіть без активного налагодження. Тому start_with_request=trigger чи окремий образ/профіль з Xdebug, а не постійно ввімкнений режим. У продакшені Xdebug не встановлюють узагалі.
Докладніше в документації: Laravel Sail: налагодження з Xdebug

Як налаштувати Xdebug для Laravel у Docker і чому IDE не отримує з'єднання?

Схожі питання