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

  1. Настройки роутера

  2. Настройки IDE (Php Storm)

  3. Настройка браузера и отладка

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

Мой DockerFile пример с командами установщика ( для удобства прикрепляю целиком, чтобы вы не гадали какой порядок тех или иных команд )

Dockerfile
FROM php:8.1-fpm 

USER root 

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

      apt-utils \ 

      libpq-dev \ 

      curl \ 

      libpng-dev \ 

      iptables-persistent \ 

      libzip-dev \ 

      libfreetype6-dev \ 

      libjpeg62-turbo-dev \ 

      zip unzip \ 

      iputils-ping \ 

      git && \ 

      docker-php-ext-install pdo_mysql && \ 

      docker-php-ext-install bcmath && \ 

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

      docker-php-ext-install gd && \ 

      docker-php-ext-install zip && \ 

      docker-php-ext-install exif && \ 

      pecl install xdebug && \ 

      docker-php-ext-enable xdebug && \ 

      apt-get clean && \ 

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

 

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

 

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

 

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

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


# Install composer 

ENV COMPOSER_ALLOW_SUPERUSER=1 

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

    --filename=composer \ 

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

 

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 например на сайте 2ip

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

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

    • В панели настроек найдите раздел с port forwarding. ( он может находиться в network или в разделе сетевой экран )

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

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

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

    • Для проверки запросов можно использовать простую утилиту dbgpClient от xdebugger. Ее можно установить по ссылке и запустить из терминала локальной машины с помощью ./dbgpClient-macos

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

      • В случае , если 9003 порт уже занят - мы можем его убить с помощью sudo kill -9 <PID>а сам PID посмотреть с помощью команды sudo lsof -i :9003

    • После запуска кидаем запрос с самой локальной машины на себя же с помощью команды telnet 127.0.0.1 9003 (если нет telnet , то установите эту утилиту командой brew install telnet. Если нет homebrew - то устанавливайте его )

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

  2.  Для проверки с виртуалки (заходим на виртуалку) и делаем так: curl -Iv <белый ip>:9003 

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

      • sudo apt update 

      • sudo apt install curl

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

    Если курл прошел успешно в окне терминала с запущенной утилитой xdebug появится строка: Connect from <ip виртуалки>:<port>

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

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

1.2 Настройки PhpStorm

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

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

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

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

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

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

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

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

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

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

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

    • Ставим галку на filter debug by ide key и вводим в поле ide key строку 

    • “PHPSTORM” - без кавычек.

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

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

  1. В зависимости от браузера вам нужно установить расширение которое должно называться Xdebug Helper

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

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

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

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