Настройка Xdebug 3 + PhpStorm на Windows + WSL + Docker

Всем привет! В данной статье расскажу о том, как настроить 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.d

2.В папке 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=debug

start_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-gateway

host-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ти минут для его настройки. Но в последствии вы экономите кучу времени по поиску ошибок.

Оставить комментарий