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 теж є чудовим джерелом, включаючи інформацію про налаштування, інструменти, параметри конфігурації та інше.