PHP, DOCKER & XDEBUG: їжа чи інструкція до застосування

У версіях Xdebug до версії 3 налаштування покрокового налагодження для коду всередині контейнерів Docker часто було, м'яко кажучи, складним завданням. Однак у версії 3 це стало майже тривіально. Це короткий посібник допоможе розібратися в тому, що потрібно зробити, незалежно від того, який (підтримуваний) текстовий редактор чи IDE використовується.

Що знадобиться?

Щоб дотримуватися цього посібника, переконайтеся, що у вас встановлено Docker для вашої операційної системи, в ідеалі остання версія, і один з підтримуваних клієнтів Xdebug. Ви можете знайти всі інструкції, необхідні для встановлення Docker – незалежно від того, чи ви використовуєте Linux, macOS або Windows – у документації по Docker.

Базова конфігурація Docker Compose

Для простоти припустимо, що ваша конфігурація Docker Compose, що зберігається у файлі docker-compose.yml у корені каталогу проекту, виглядає так, як показано на прикладі нижче.

./docker/php/Dockerfile FROM php:7.4-apache RUN pecl install xdebug \ && docker-php-ext-enable xdebug

docker-compose.yml

version: ‘3’

services:

  php:
    build: ./docker/php/
    ports:
      — 8080:80
    volumes:
      — ./:/var/www/html

Вихідний код програми, незалежно від того, чи він використовує такі фреймворки, як Laravel або Symfony, знаходиться в кореневому каталозі проекту на машині розробки і буде доступний для контейнера в /var/www/html.

Установка Xdebug 3 у контейнер PHP

Контейнер php використовує файл користувача Dockerfile (./docker/php/Dockerfile) для визначення кроків збірки, які ви можете побачити в прикладі нижче. Це пов'язано з тим, що Xdebug не поставляється "в комплекті" з офіційними контейнерами PHP Docker Hub.

./docker/php/Dockerfile

FROM php:7.4-apache

RUN pecl install xdebug \
    && docker-php-ext-enable xdebug

Однак для його встановлення та включення потрібно всього два додаткові кроки, як ви можете бачити вище. Це:

• Установка за допомогою Pecl
• Увімкнення його за допомогою docker-php-ext-enable. Ця команда позбавляє нас необхідності писати власний сценарій оболонки.

Налаштування Xdebug для покрокової налагодження

Коли Xdebug встановлений та увімкнений, нам потрібно включити покрокове налагодження. Для цього створіть конфігураційний файл: docker/php/conf.d/xdebug.ini; та шляхи, якщо у вас ще не налаштована структура каталогів.

Щоб заощадити час, можна використовувати наступні команди.

mkdir -p docker/php/conf.d
touch docker/php/conf.d/xdebug.ini

У докер/php/conf.d/xdebug.ini додайте наступну конфігурацію для налаштування Xdebug.

zend_extension=xdebug

[xdebug]
xdebug.mode=develop,debug
xdebug.client_host=host.docker.internalxdebug.idekey=»VSCODE»xdebug.client_port=9003Xdebug.start_with_request=yes

Пояснення файлу xdebug.ini:

• mode — цей параметр визначає, які функції Xdebug увімкнені. Ми встановили develop для включення допоміжних засобів розробки, таких як отримання покращених повідомлень про помилки, та debug для включення покрокової налагодження.
• client_host - цей параметр повідомляє Xdebug IP-адресу або ім'я хоста комп'ютера, на якому працює ваш текстовий редактор або IDE.
• client_port - цей параметр повідомляє порт, до якого Xdebug намагається підключитися на віддаленому хості
• idekey — цей параметр вказує, який ключ IDE Xdebug повинен передати клієнту налагодження або проксі-серверу, ми встановили “VSCODE”, але це може бути будь-який кастомний ключ, який згодом буде вказаний у розширенні браузера
• start_with_request - цей параметр визначає, чи активуються трасування функції, статистика складання сміття, профільування або покрокове налагодження на початку запиту PHP. Налаштування його в yes вказує Xdebug завжди ініціювати сеанс налагодження.

Потім у визначенні сервісу php у docker-compose.yml додайте наступний запис елемент volumes.

— ./docker/php/conf.d/xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

А також створіть новий елемент extra_hosts на тому ж рівні, що і volumes:

extra_hosts:
- "host.docker.internal:host-gateway"

Створивши ini-файл та оновивши docker-compose.yml, щоб використовувати його у php-контейнері, перезапустіть та перезберіть його, виконавши наступну команду.

docker-compose up -d -build

Прапор build створює образи перед запуском контейнерів. Дуже важливо використовувати цей прапор, тому що без нього зміни, які ми зробили в docker/php/Dockerfile, не набудуть чинності.

Налаштування Xdebug у текстовому редакторі або IDE

Тепер, коли ми закінчили налаштування PHP-контейнера, нам потрібно налаштувати наш клієнт. Це залежить від клієнта, який ви використовуєте. Для цілей цієї статті я опишу налаштування у VSCode та PhpStorm.