Всем привет! В данной статье расскажу о том, как настроить Xdebug на PhpStorm в довольно популярном рабочем окружении Windows + WSL + Docker.
Предисловие.
Изначально, когда я познакомился с Docker, я разрабатывал свои проекты в Windows. В этом окружении я настроил Xdebug, который замечательно работал и меня всё устраивало. Но время шло, проекты тупили, популярность WSL росла, и настало время переезда. Разобравшись с в WSL (я использую Ubuntu 20.04) и переместив туда все проекты, я был доволен как слон с логотипа PHP. Но через некоторое время мне понадобился Xdebug, и стандартная настройка Docker + Windows уже не работала. И как ни странно, статей в интернете по настройке Xdebug именно в этом окружении оказалось не так много, а та информация, которая там была, либо устарела, либо была неполная. Потратив некоторое количество времени, собрав всё в единое целое, я всё-таки запустил Xdebug. Далее, постараюсь максимально кратко рассказать, как его настроить.
Используемый стек на момент написания статьи:
- Windows 11
- Docker Desktop 4.22.1 (основное приложение php строится на основе образа php:8.1-fpm-alpine)
- WSL2 (Ubuntu 20.04)
- Xdebug 3.2.2
- PhpStorm 2023.2.1
Настройка Xdebug
1. О том как установить Xdebug внутри контейнера я расписывать не буду, есть очень много развернутых гайдов в интернете. Я просто приведу пример, как я устанавливаю Xdebug в Dockerfile
#Installing xdebug
RUN apk add --no-cache --virtual .build-deps $PHPIZE_DEPS \
&& apk add --update linux-headers \
&& pecl install xdebug-3.2.2 \
&& docker-php-ext-enable xdebug \
&& apk del -f .build-deps
...
COPY ./conf.d /usr/local/etc/php/conf.d2.В папке conf.d у меня создан файл xdebug.ini, который с помощью команды COPY ./conf.d /usr/local/etc/php/conf.d отправляется в контейнер:
[xdebug]
xdebug.client_host=host.docker.internal
xdebug.start_with_request=trigger
xdebug.idekey=PHPSTORM
xdebug.mode=debugstart_with_request=trigger- означает что мы будет запускать Xdebug только после определенного триггера, которым является значение XDEBUG_SESSION. Подробнее в документации.
3. Нам необходимо разрешить прямое соединение изнутри контейнера Docker c нашей WSL. В docker-compose.yml вашего приложения добавляем extra_hosts:
php-moonshine:
build:
context: ./docker/PHP8
args:
docker_user: ${DOCKER_USER}
container_name: php-moonshine
volumes:
- ${LOCAL_PATH_HOST}:${APP_PATH}
depends_on:
- db-moonshine
extra_hosts:
- host.docker.internal:host-gatewayhost-gateway автоматически пропишет ip адрес вашего локального компьютера.
4. Добавляем Docker в PhpStorm.
5. Добавляем интерпретатор php из нашего контейнера, здесь подробнее по шагам.
Сначала кликаем по основному пункту PHP, нажимаем на троеточие:
Далее выбираем вариант с докером:
Устанавливаем вариант Docker, в ImageName выбираем нужный образ, в котором работает проект:
Должно получится как показано на скриншоте ниже, мы видим версию Php и Xdebug:
6. Добавляем сервер:
Обратите внимание на порт, он здесь всегда 80й. Это НЕ порт вашего приложения, которое работает в браузере, а именно локального сервера. Прописываем пути до корня проекта как на скриншоте, так же рекомендую сразу добавить путь до папки public, если у вас Laravel приложение.
7. Теперь нужно создать наш дебагер и добавить в него настроенный сервер:
Добавляем PHP Remote Debug, выбираем сервер и пишем в IDE key ключ из пункта 2 (xdebug.idekey):
8. Осталось только запустить прослушивание, поставить Breakpoint и... ничего не произойдет. Помните в пункте 2 параметр start_with_request=trigger? Нам необходимо запустить Xdebug, для этого мы либо через URL пишем http://localhost?XDEBUG_SESSION=1 или в самом коде ставим куку. Я для примера использую следующий код, который запускает Xdebug только в локальном окружении:
Если не хотите заморачиваться, можете пропустить этот пункт и поставить start_with_request=true. В любом случае, рекомендую попробовать разные варианты и использовать тот, который вам больше удобен.
9. Запускаем прослушивание:
Ставим брейкпоинт:
Заходим в браузер и наблюдаем работу Xdebug:
Заключение
На этом всё. От себя добавлю, что Xdebug очень мощный инструмент, который позволяет быстро определить ошибки, найти баги, или просто разобраться в логике работы программы, благодаря стеку вызовов, по которому можно спокойно пройтись прямо в PhpStorm. После того, как разберетесь с первоначальной установкой, далее вам потребуется не более 5ти минут для его настройки. Но в последствии вы экономите кучу времени по поиску ошибок.
Kevin