Гайд 2023 Xdebug в PHPSTORM + Virtual server + Docker для macOS с пробросом портов

Предварительно необходимо убедиться, чтобы в контейнере под php-fpm у вас был пакет Xdebug. Нужно либо установить в ручную, либо зашить в Dockerfile - конечно же второе будет лучше, т.к не придется при перезапуске делать одно и то же действие с установкой.

Мой DockerFile пример с командами установщика

1. FROM php:8.1-fpm

2. USER root

3. RUN apt-get update && apt-get install -y \

4. apt-utils \

5. libpq-dev \

6. curl \

7. libpng-dev \

8. iptables-persistent \

9. libzip-dev \

10. libfreetype6-dev \

11. libjpeg62-turbo-dev \

12. zip unzip \

13. iputils-ping \

14. git && \

15. docker-php-ext-install pdo_mysql && \

16. docker-php-ext-install bcmath && \

17. docker-php-ext-configure gd --with-freetype --with-jpeg && \

18. docker-php-ext-install gd && \

19. docker-php-ext-install zip && \

20. docker-php-ext-install exif && \

21. pecl install xdebug && \

22. docker-php-ext-enable xdebug && \

23. apt-get clean && \

24. rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* \

25.  

26. COPY ./.docker/php/conf.d/php.ini /usr/local/etc/php/conf.d/php.ini

27.  

28. COPY ./.docker/php/conf.d/xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

29.  

30. RUN rm /usr/local/etc/php-fpm.d/www.conf

31. COPY ./.docker/php/conf.d/www.conf /usr/local/etc/php-fpm.d/www.conf

32.  

33. # Install composer

34. ENV COMPOSER_ALLOW_SUPERUSER=1

35. RUN curl -sS https://getcomposer.org/installer | php -- \

36. --filename=composer \

37. --install-dir=/usr/local/bin

38.  

39. WORKDIR /var/www/myproject

Также в конфигурации xdebug.ini, которая должна лежать по пути /php/conf.d/xdebug.ini

Должны быть следующие настройки 

xdebug.start_with_request=yes

xdebug.mode=debug

xdebug.client_host=<ваш белый айпи>

xdebug.log="/tmp/xdebug.log"

xdebug.client_port=9003

xdebug.idekey=PHPSTORM

Если все ок перезапускаем контейнера на всякий случай с флагом билд

sudo docker-compose up -d —build

Если не ок, то разбираемся с докером.

1.1 Настройки роутера

1. Убедитесь, что у вас белый айпи на роутере 

• Для этого можно попробовать перезагрузить роутер и посмотреть меняется ли ip например на сайте https://2ip.ru/

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

2. После того как вы убедились, что ip статический (белый) - необходимо пробросить порты на роутере. Для этого провалитесь по адресу http://192.168.0.1 для некоторых роутеров, или http://192.168.1.1 - в форме логина, если никто не менял пароли можно посмотреть креды на обратной стороне роутера. По умолчанию это что то типа admin:admin.

• В панели настроек найдите раздел с port forwarding.

• Необходимо открыть 9003 порты для wan сети, добавив строку в таблице для протоколов TCP&UDP. В некоторых ситуациях нужно также указать ip назначения - это может быть в контексте вашего локального устройства, или устройства, которое отправляет запросы (ip виртуалки). В моем случае это было локальное устройство. Посмотреть айпи устройства в локальной сети можно с помощью команды  ipconfig getifaddr en0  в случае если у вас macos и нету кабеля ethernet напрямую в устройство. Если кабель есть то вместо 0 на конце команды поменяйте на единицу. 

• После открытия портов на всякий случай можно перезагрузить роутер

3. Чтобы убедиться, что у нас нет ошибок на уровне портов и коннекта необходимо проверить это дело следующим образом: 

Кидаем запрос с самой локальной машины на себя же с помощью команды telnet 127.0.0.1 9003 (если нет telnet , то установите его )

Если запрос прошел успешно в окне терминала с запущенной утилитой xdebug появится строка коннекта. Если же нет, то скорее всего у вас включен брэндмауэр с блокировкой доступов ( другими словами firewal ) - который можно выключить в системных настройках -> конфиденциальность и безопасность в разделе брэндмауэра. 

Для проверки запросов с виртуальной машины на локальную для начала можно использовать простую утилиту dbgpClient от xdebugger. Ее можно установить по ссылке https://xdebug.org/docs/dbgpClient и запустить из терминала с помощью ./dbgpClient-macos

• Он начнет прослушивать порт 9003 и напишет Waiting for debug server to connect on port 9003.

• В случае , если 9003 порт уже занят - мы можем его убить с помощью

 sudo kill -9 <PID>

 а сам PID посмотреть с помощью команды

 sudo lsof -i :9003

После того как утилита curl установлена и запущена без проблем - нам нужно зайти на виртуальную машину и кинуть curl запрос с флагом -Iv на наш белый айпишник с портом 9003 

• curl -Iv <белый ip>:9003 

• Возможно придется установить curl , если он выдаст ошибку curl not found. Установить вы его можете следующими командами для ubuntu

1. sudo apt update 

2. sudo apt install curl

3. И проверьте что он установлен корректно curl –version

• Если курл прошел успешно в окне терминала с запущенной утилитой xdebug появится строка:

Connect from <ip виртуалки>:<port>

Если курл не прошел, то возможно на виртуальной машине также есть настройки файрвола , которые запрещают 9003 порт. Ну и для теста можно попытаться и установить правила разрешения в ручную через утилиту ufw  -  sudo ufw status (проверка портов)

В xdebug.ini ставим белый айпишник, перебилдим контейнера на всякий случай и можно переходить к настройкам PHPSTORM.

1.2 Настройки PhpStorm

Предварительно добавьте ssh конфигурацию со своим удаленным сервером в IDE, чтобы не подключаться по ssh каждый раз руками.

1. Сначала в настройках php storm вам необходимо создать сервер для php интерпретатора. 

• Зайдите в преференсы IDE -> php -> servers 

• И создайте сервер, если ваш сайт работает на домене, в разделе host надо указать домен без протокола (example.com) , если на домене не установлен https - указываем порт 80, если установлен , то указываем 443 порт

• Ставим галку на Use path mappings.

2. Далее переходим в раздел PHP->Debug и в Xdebug подразделе указываем 9003 порт , ставим галку на can accept external connections и на остальных 3х пунктах ниже

3. Следующим пунктом нужно настроить удаленный php интерпретера - для этого переходим в сам раздел php, где строка CLI интерпретера в правом углу нажимаем троеточие, в левом сайдбаре нажмем плюсик и создадим новую конфигурацию для интерпретера

• В Name вводим что угодно , выбираем ssh конфигурацию с нашей виртуалкой и в php executable указываем путь до php (стандартно он будет /usr/bin/php)

• Остальное по вашему желанию, для меня это было не обязательно, не забудьте сохранить все и убедиться что в настройках PHP подтянулась новая конфигурация в строке CLI интерпретера, а также появилась строка path mappings 

4. Теперь в правом верхнем углу IDE находим дропдаун слева от зеленого жучка , нажимаем ПКМ и переходим в edit configuration. Здесь необходимо создать конфигурацию для процесса дебага

• Создаем на плюсик в левом сайдбаре PHP Remote Debug, имя вводим любое 

• Сервер выбираем , который мы создавали в PHP->Servers

• Ставим галку на filter debug by ide key и вводим в поле ide key строку “PHPSTORM” - без кавычек.

• Не забудьте закрыть утилиту dbgpClient , т.к он не даст запустить прослушивание IDE , если на 9003 порту еще что то слушается.

Далее нажимаем на трубку в правом верхнем углу рядом с зеленым жучком (трубка тоже должна показывать зеленого жучка иконку рядом) - таким образом мы запустили процесс отслушки порта 9003 для дебага через IDE 

6. Далее в дропдауне в верхнем правом углу выбирайте имя новой конфигурации и нажимайте на зеленого жука. 

7. Внизу должна открыться панель с дебагом. Заходим в табах на раздел debugger и ставим точки остановы в своем коде

После этого переходим к следующему этапу 

1.3 Расширение xdebug helper и отладка

1. В зависимости от браузера вам нужно установить расширение которое должно называть Xdebug Helper https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc 

2. Далее зайти в его параметры через ПКМ по иконке расширения и в контекстном меню пункт Параметры , где указать IDE KEY  “PHPSTORM” - без кавычек 

3. Переходим на домен или ip сервера, который вы указывали в конфигах IDE - PHP -> Servers. Нажимаем на расширение и выбираем режим debug в выпадающем списке.

4. Кидаем запрос еще раз и открываем IDE , в разделе debugger должен пойти процесс отлова брейкпоинтов 

Приятной всем отладки!