Шпаргалка по PHP: настройка Xdebug 3.x в PhpStorm через Docker для Laravel 11

Настройка Xdebug в PhpStorm с Docker — важный этап для эффективной отладки PHP-приложений. В этом руководстве разберём:

• •

  ✅ Готовый конфиг по установки и настройки Xdebug в Docker-контейнере

• •

  ✅ Проверенные настройки для PhpStorm

• •

  ✅ Особенности работы с Laravel

• •

  ✅ Решение частых проблем (host.docker.internal, порты 9003)

👋 Перед тобой готовая шпаргалка по настройке Xdebug для Laravel 11 в Docker-окружении. Всё уже проверено и работает — осталось только повторить!

Позитивно

👋 Перед тобой готовая шпаргалка, проверенная и рабочая, которая содержит пошаговую инструкцию по настройке IDE PhpStorm для работы с уже сконфигурированным PHP-проектом Laravel 11 в Docker-окружении — тебе остается только повторить!

Шаг 1. Клонировать подготовленный репозиторий

Это руководство описывает, как настроить среду разработки PhpStorm для взаимодействия с готовым PHP-проектом. В качестве примера конфигурации вы можете использовать проект, расположенный в открытом доступе:

1. 1.

   Клонировать проект из репозитория: https://github.com/ekangash/laravel-infrastructure

2. 2.

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

Шаг 2: Установка соединения Docker с PhpStorm через Socket

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

Как подключить Docker к PhpStorm:

1. 1.

   Откройте настройки PhpStorm: Перейдите в меню File (Файл) -> Settings (Настройки).

2. 2.

   Найдите раздел Docker: В открывшемся окне настроек перейдите в раздел Build, Execution, Deployment (Сборка, Выполнение, Развертывание) -> Docker.

3. 3.

   Добавьте новое Docker-подключение: В левом верхнем углу окна настроек Docker нажмите на значок "+" (добавить). Это действие позволит создать новую конфигурацию подключения к Docker.

4. 4.

   Проверьте успешность подключения: После добавления новой конфигурации PhpStorm автоматически попытается установить соединение с Docker-контейнером, запущенным на вашем локальном хосте.

5. 5.

   Убедитесь в наличии сообщения об успехе: В нижней части вкладки "Docker" должно отобразиться зеленое сообщение "Connection successful" (Соединение установлено успешно). Это является подтверждением того, что PhpStorm успешно подключился к Docker, и дальнейшая работа будет стабильной.

Шаг 2: Добавление слушателя PHP-сервера в PhpStorm для отладки Docker-приложений

Для корректной отладки PHP-приложений, запущенных в Docker-контейнерах, необходимо настроить связь между PhpStorm и вашим Docker-окружением. Этот шаг описывает процесс добавления нового PHP-сервера в PhpStorm, который будет использоваться для маппинга путей и запуска отладки.

Как добавить PHP-сервер в PhpStorm для работы с Docker:

1. 1.

   Откройте настройки PHP-серверов: В главном меню PhpStorm перейдите в раздел File (Файл) -> Settings (Настройки) -> PHP -> Servers.

2. 2.

   Добавьте новый сервер: В открывшемся окне "Servers" нажмите кнопку "+" (Add insert) или значок плюса. Это действие создаст новую запись для вашего PHP-сервера.

3. 3.

   Укажите параметры сервера: В появившемся интерфейсе заполните следующие поля, основываясь на конфигурации вашего Docker-проекта:

• •

  Name (Имя): Введите имя для вашего сервера.

Примечание

Важно: Это имя должно совпадать со значением переменной окружения PHP_IDE_CONFIG, указанной в файле docker-compose.yaml для сервиса php-fpm. Для текущего репозитория это выглядит так: PHP_IDE_CONFIG: "serverName=${APP_NAME}".

• •

  Host (Хост): Укажите внешний хост вашего приложения, на котором оно доступно. В большинстве случаев для локальной разработки это значение будет localhost.

• •

  Port (Порт): Введите внешний порт, который вы пробросили (замаппили) для контейнера nginx в вашем файле docker-compose.yaml. Именно на этом порту ваше приложение доступно через браузер.

• •

  Use path mappings (Использовать сопоставление путей): Обязательно установите галочку напротив этой опции. Это позволит PhpStorm правильно сопоставлять локальные файлы проекта с файлами внутри Docker-контейнера.

4. 4.

   Настройте сопоставление путей (Path Mappings):

• •

  В нижней части окна "Add New Server" добавьте новую запись в разделе "Path mappings".

• •

  В поле "File/Directory" указан по умолчанию абсолютный путь к корневой директории вашего PHP-проекта на вашем локальном компьютере.

• •

  В поле "Absolute path on the server" укажите абсолютный путь к корневой директории вашего приложения внутри Docker-контейнера. Для нашего проекта конфигураций это значение будет /var/www/.

Шаг 3: Настройка PHP-интерпретатора из Docker-контейнера в PhpStorm

Для обеспечения корректной работы отладчика Xdebug и статического анализа кода в PhpStorm необходимо указать интерпретатор PHP, который запущен внутри вашего Docker-контейнера. Этот шаг подробно описывает процесс настройки CLI Interpreter в PhpStorm для использования PHP-FPM из вашего Docker-окружения.

Как настроить PHP CLI Interpreter из Docker в PhpStorm:

1. 1.

   Перейдите в настройки PHP: В главном меню PhpStorm выберите File (Файл) -> Settings (Настройки) -> PHP.

2. 2.

   Укажите уровень языка PHP: В поле PHP language level выберите версию PHP, которая используется в вашем контейнере php-fpm в Docker.

3. 3.

   Настройте CLI Interpreter: Напротив поля CLI Interpreter, нажмите на кнопку с тремя точками (...). Откроется окно PHP Interpreters.

4. 4.

   Добавьте новый интерпретатор: В окне PHP Interpreters нажмите на значок "+" (добавить новый интерпретатор), расположенный в левом верхнем углу.

5. 5.

   В появившемся меню выберите опцию Docker Compose. Откроется следующее окно с настройками Docker:



6. 6.

   Выберите способ подключения к Docker в зависимости от вашей операционной системы:

• •

  Для Linux:

• •

  Выберите Docker Compose.

• •

  В разделе Server нажмите кнопку New и оставьте параметры подключения Docker по умолчанию (если вы еще не настраивали подключение на предыдущих шагах).

• •

  В поле Service выберите имя вашего сервиса php-fpm из файла docker-compose.yaml.

• •

  Для Windows:

• •

  Выберите Docker.

• •

  В разделе Server нажмите кнопку New и оставьте параметры подключения Docker по умолчанию.

• •

  В поле PHP executable выберите ваш сервис php-fpm, возможно, с указанием тега :latest (например, your-php-fpm-docker-server-name:latest).

7. 7.

   Проверьте версию PHP и Xdebug: После выбора сервиса Docker PhpStorm должен автоматически определить версию PHP и наличие установленного расширения Xdebug внутри вашего контейнера. Убедитесь, что отображаемая информация корректна.



8. 8.

   Настройте сопоставление путей (Path Mappings) для CLI Interpreter: Выберите добавленный CLI Interpreter и перейдите на вкладку Path mappings. Укажите соответствие между локальным путем к файлам вашего проекта на компьютере и абсолютным путем к этим же файлам внутри контейнера php-fpm. Этот путь должен совпадать с настройками volumes в вашем файле docker-compose.yaml.

После выполнения всех шагов конфигурации вашего PHP-приложения, работающего в Docker, для окончательной проверки корректности настройки Xdebug рекомендуется установить точку останова (breakpoint) в ключевой точке входа вашего приложения (например, в index.php или bootstrap/app.php для Laravel).

Затем, запустив отладку в PhpStorm и выполнив запрос к вашему приложению через браузер, убедитесь, что выполнение кода останавливается на установленной вами точке. Успешная остановка скрипта и активация панели отладки в PhpStorm будут свидетельствовать о корректной настройке связки Docker, Xdebug и PhpStorm, позволяя вам эффективно отлаживать ваше PHP-приложение.

После того как вы настроили все по инструкции, чтобы убедиться, что отладка Xdebug работает как надо, сделайте вот что:

1. 1.

   Поставьте специальную метку (точку остановки) в самом начале вашего приложения (например, в файле index.php или bootstrap/app.php, если у вас Laravel).

2. 2.

   Потом запустите отладку в PhpStorm и откройте свою страницу в браузере. Если все правильно, программа остановится там, где вы поставили метку, а в PhpStorm появится окошко отладки.

Это значит, что Docker, Xdebug и PhpStorm работают вместе, и вы сможете легко находить ошибки в своем PHP-коде.

Частые проблемы и их решения

Иногда возникают проблемы с настройкой xdebug client host docker. Убедитесь, что ваш контейнер Docker может видеть хост, используя host.docker.internal. Если это не помогает, попробуйте использовать IP-адрес вашей машины.

Для отладки php xdebug настройка также важен правильный порт. Если порт 9003 уже занят, выберите другой порт и обновите конфигурации.

Примечание настроенного Laravel приложения:

В конце проделанных действий необходимо перезапустить Docker контейнеры.

Чтобы проверить результаты, нужно поставить точку остановки в точке входа приложения, в примере можно в файле bootstrap/app.php, включить режим отладки (иконка телефона в верхнем правом углу) и перейти в браузере по адресу http://localhost:{APP_PORT}. В PhpStorm должна открыться панель отладки.

Заключение

Настройка Xdebug в PhpStorm с использованием Docker требует некоторых усилий, но при правильном подходе это становится достаточно простым процессом. Следуя этим шагам, вы сможете легко настроить docker xdebug phpstorm и использовать мощные возможности отладки вашего кода. Docker xdebug 3 позволяет использовать новейшие функции Xdebug и значительно улучшает процесс отладки. Удачи в разработке и отладке вашего PHP-приложения!