Налаштування Xdebug з Docker та PHP 8.4 всього за одну хвилину

Xdebug відомий своїм складним налаштуванням. Проте я покажу вам, що інсталяція Xdebug може бути простою. Насправді, я впевнений, що ви зможете почати використовувати Xdebug із Docker приблизно за хвилину.

Добре, можливо, деяким із вас знадобиться кілька хвилин :)

Ми налаштуємо його в середовищі Laravel з PHP 8.4 та Xdebug v3.4.0, актуальними на момент написання.

Щоб настроїти Xdebug на Docker, нам знадобиться:

• Файл Dockerfile, який встановлює модуль Xdebug і його конфігурацію
• Файл compose.yaml для запуску контейнера
• Редактор або IDE, яка буде клієнтом Xdebug

# Налаштування проекту

У цьому пості ми використаємо Apache для спрощення налаштування сервера, однак код Dockerfile буде ідентичний налаштуванню Xdebug у образі PHP-FPM.

Почнемо з налаштування демонстраційного проекту:

laravel new xdebug-demo --git --no-interaction
cd xdebug-demo
mkdir -p build/php/conf.d build/apache
touch compose.yaml \
    build/Dockerfile \
    build/php/conf.d/xdebug.ini \
    build/apache/vhost.conf

Ми створили папки та файли через командний рядок, але ви можете зробити це на свій розсуд. Окрім звичних Docker-файлів, ми також створили файл vhost.conf для налаштування кореневого веб-шляху нашого застосунку.

# Налаштування Docker-образу

Далі додайте наступне до файлу build/Dockerfile:

Dockerfile містить багато рядків, тож розглянемо найважливіший код, щоб допомогти вам зрозуміти, як налаштувати Xdebug. Спочатку ми використовуємо багатошарове будування, щоб налаштувати Xdebug у розробницьких середовищах. Перед етапом development є етап base, що містить базові налаштування, необхідні нашому образу, такі як PHP-розширення, котрі потрібні в будь-якому середовищі, та налаштування Apache.

На наступному етапі development ми копіюємо версію файлу PHP.ini для розробки і конфігураційний файл xdebug.ini, у якому зберігатимемо наші налаштування Xdebug. Ми використовуємо v3.4.0, яка підтримує PHP 8.4 і є актуальною на момент написання.

Останній, app, етап використовується нашим застосунком у виробничих налаштуваннях. Використання цільового етапу app виключає налаштування Xdebug і використовує версію php.ini для виробництва.

# Apache Vhost

Нам не потрібно навчатися, як налаштовувати Apache; ми просто хочемо швидко продемонструвати, як легко налаштувати Xdebug на Docker. Додайте наступний код до файлу build/apache/vhost.conf, який копіюється в Docker-образ для вказівки на код застосунку:

<VirtualHost *:80>
 ServerAdmin webmaster@localhost
 DocumentRoot /srv/app/public
 
 <Directory "/srv/app/public">
 AllowOverride all
 Require all granted
 </Directory>
 
 ErrorLog ${APACHE_LOG_DIR}/error.log
 CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

# Конфігурація Xdebug

Далі потрібно налаштувати Xdebug через файл xdebug.ini. Додайте наступне, якщо ви слідуєте інструкціям:

; build/php/conf.d/xdebug.ini file
[xdebug]
xdebug.mode = debug
 
xdebug.client_host = host.docker.internal
 
; Або використовуйте IP-адресу хоста:
; xdebug.client_host = 192.168.86.203
 
xdebug.start_with_request = yes

Ці налаштування потрібні для визначення клієнтського хоста. Оскільки ми використовуємо Docker-мережу, Xdebug має знати, як спілкуватися з нашим хост-комп'ютером. Якщо ви використовуєте Docker Desktop, Docker має хост host.docker.internal, що вказує на ваш комп'ютер.

Якщо ні, вам потрібно знайти локальну IP-адресу вашого комп'ютера і використовувати її. Хоча ми могли б вказати цю інформацію через змінну середовища, я залишу це для наступного посту.

Також ми використовуємо xdebug.start_with_request = yes, щоб Xdebug завжди активувався з кожним запитом. Ви можете вимкнути Xdebug через інтерфейс редактора, коли він не потрібен, але він завжди намагатиметься встановити з'єднання.

# Запуск образу

Перед перевіркою з'єднання Xdebug потрібно налаштувати контейнер застосунку. Ми скористаємося Docker Compose, щоб запустити наш застосунок, додавши наступне до compose.yaml:

services:
  app:
    build:
      context: .
      dockerfile: build/Dockerfile
      target: development
    ports:
      - "8080:80"
    volumes:
      - .:/srv/app

Наша служба app націлена на етап development нашого будування, монтує обсяг, щоб ми могли змінювати код без перебудови образу, і використовує порт 8080 для локальної подачі застосунку.

Тепер ми можемо побудувати та запустити наш образ за допомогою Docker Compose:

docker compose up --build -d

Ця команда створить образ, запустить контейнер і працюватиме у фоновому режимі. На цьому етапі Xdebug готовий приймати з'єднання, однак нам потрібно провести кілька налаштувань у IDE.

# Налаштування PhpStorm

Ми будемо використовувати PhpStorm, але ви можете вибрати будь-який редактор, який підтримує Xdebug. Оскільки ми використовуємо Docker, потрібно налаштувати сервер у PhpStorm, що відображає обсяг Docker на код вашого локального проекту. Для цього відкрийте Налаштування > PHP > Сервери та налаштуйте сервер localhost з відображенням /srv/app:

Якщо у вас немає сервера localhost, ви можете додати його на цій сторінці налаштувань, використовуючи порт 8080 і вибравши налагоджувач Xdebug. Відображення сервера дозволяє нашому IDE зрозуміти, як співвіднести трасування стеку сервера з файлами в проекті.

Тепер ми готові активувати Xdebug, натиснувши на значок "Bug" у верхньому правому меню, який говорить "Почати прослуховування PHP Debug з'єднань" при наведенні на нього:

Коли ви на нього натискаєте, значок має стати зеленим.

Останнє, що потрібно зробити — це встановити точку зупинки. Відкрийте файл routes/web.php та встановіть точку зупинки на єдиному рядку домашнього маршруту:

Якщо ви відкриєте свій проект у веб-браузері (localhost:8080), PhpStorm має запросити вас на з'єднання вперше. Після цього він автоматично зупиниться на будь-яких точках зупинки, які ви встановите. Коли ви закінчите відладку, можете натиснути на значок Bug, щоб відключити з'єднання Xdebug.

# Додаткові ресурси

Тепер ви повинні мати можливість використовувати Xdebug з вашим проектом! Я також подав вам бонусну тему — використання багатошарових образів для налаштування інструментів розробки і окремого етапу для виробничих налаштувань. Використання багатошарових будівель дозволяє зробити ваші образи більш гнучкими.

Якщо у вас виникнуть труднощі з частиною налаштування Xdebug в редакторі, PhpStorm має детальну документацію про те, як налаштувати Xdebug. Документація Xdebug теж є чудовим джерелом, включаючи інформацію про налаштування, інструменти, параметри конфігурації та інше.