Налаштовуємо Xdebug у PHPStorm

Одним із найголовніших процесів у програмуванні вважається налагодження. За допомогою відладчика можна подивитися, що відбувається в програмі, які функції виконуються, що зберігається у змінних, а також виконати все покроково і точно зрозуміти, на якому рядку і за яких значень змінних трапляється помилка.

Наприклад, для PHP використовується відладчик Xdebug, PHPStorm - це одне з найпопулярніших середовищ розробки. Далі розглянемо, як налаштувати Xdebug у PhpStorm для налагодження на локальному комп'ютері та в Docker.

Налаштовуємо XDEBUG у PHPSTORM

Поговоримо про те, як здійснюється налагодження на локальному сервері.

Весь процес розглянемо на прикладі Ubuntu та інтерпретатора PHP, налаштованого разом з Apache. Для інших конфігурацій шляхи до файлів можуть відрізнятися, але суть від цього не змінюється. Налагоджувач Xdebug дає змогу призупиняти виконання коду, дивитися стек викликів і вміст змінних. Єдиний його мінус - немає зручного інтерфейсу управління. З метою управління налагодженням зазвичай використовують IDE. Але IDE не може ніяк повідомити налагоджувачу, що треба запустити налагодження, тому що вона відповідає тільки за код. Для цього знадобиться ще розширення для браузера Debug Helper, за допомогою якого ви зможете увімкнути режим налагодження.

Спочатку необхідно встановити Xdebug. Для цього виконайте:

$ sudo apt install xdebug

Щойно процес встановлення Xdebug завершився, слід налаштувати програму так, щоб під час запуску сеансу налагодження вона намагалася під'єднатися до нашої IDE для керування налагодженням. Для цього додайте такі рядки у файл /etc/php/7.4/apache2/conf.d/20-xdebug.ini у версії Xdebug 2:

$ sudo vi /etc/php/7.4/apache2/conf.d/20-xdebug.ini
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_connect_back=1
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_autostart=false

Для нової версії найкраще використовувати інший формат:

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9000

Розглянемо налаштування докладніше. Перший параметр xdebug.mode - режим налагодження, можливі варіанти:

• develop - вмикає виведення додаткової інформації, перевизначає var_dump;

• debug - режим рядкового виконання коду, саме він потрібен у цьому випадку;

• profile - профілювання;

• trace - трасування виконання програми.

Кілька режимів вмикає одночасно при перерахуванні через кому. Другий рядок xdebug.start_with_request визначає, як запускатиметься відладчик для режимів debug, trace і їм подібних:

• yes - завжди, під час запуску php скриптів;
• no - запуск тільки з коду за допомогою спеціальних функцій;
• trigger - за запитом, за допомогою спеціальної змінної в $_ENV, $_POST, $COOKIE або в іншому масиві. Цей варіант підходить найкраще в цьому випадку, щоб відладчик не запускався, коли в цьому немає потреби.

Третя xdebug.discover_client_host має значення true, у такому разі xdebug намагається під'єднатися до хоста, переданого в заголовку HTTP_X_FORWARDED_FOR. Оскільки хост вказується в наступному рядку, в даному випадку ця можливість не потрібна. Далі вказується хост клієнта, куди треба підключиться для управління налагодженням 127.0.0.1 і порт 9000. Саме цей порт використовується в PhpStorm за замовчуванням на даний момент. Після збереження налаштувань необхідно виконати перезавантаження Apache за допомогою спеціальної команди:

$ sudo systemctl restart apache2

Далі слід налаштувати PhpStorm. Запустіть програму, потім відкрийте меню Run -> Edit Configurations. Перед вами відкриється вікно, в якому треба налаштувати відладчик.

Тиснемо кнопку + і в списку, що відкрився, вибираємо PHP Remote Debugger:

У налаштуваннях нічого не змінюємо, вказуємо тільки ім'я цього способу налагодження. Якщо сервер, з якого очікуватимуть підключення, не задати, то прийматимуться всі підключення.

Якщо потрібно змінити порт, до якого буде підключатися Xdebug, відкриваємо меню File -> Settings -> PHP -> Debug -> DBGp Proxy. Тут можна вказати потрібний порт.

Можна говорити, що тепер IDE готова. Тепер клікаємо по жуку на верхній панелі інструментів. Програма почне очікувати підключення відладчика і поставимо кілька точок зупинки в коді, просто клікнувши перед рядком із кодом:

Тепер залишається виконати налаштування браузера. Для Chrome можна завантажитиспеціальне розширення. Встановіть його і відкрийте сторінку, яку треба налагоджувати. Клацніть по значку розширення та виберіть Debug. Значок розширення стане зеленим:

Оновлюємо сторінку і повертаємося до PHPStorm. Якщо все було зроблено правильно, там запуститься сеанс налагодження. Під час першого запуску програма може попросити налаштувати відповідності локальних шляхів до файлів із віддаленими. Для локального сервера тут нічого налаштовувати не треба. просто тиснемо Accept:

Після цього відладчик зупинить виконання на обраній точці зупинки і в програмі з'явиться інтерфейс налагодження:

Тепер розберемося як налаштувати Xdebug PhpStorm і Docker.

Налагодження PHP у DOCKER

З Docker може виникнути певна складність. Оскільки налагоджувач повинен сам підключиться до IDE, необхідно прокинути хост у контейнер. В операційній системі Windows це можна зробити за допомогою адреси host.docker.internal. Але в Linux, за замовчуванням це не відбувається. Для того щоб додати таку адресу, треба додати в docker-compose такі рядки:

extra_hosts:

host.docker.internal: host-gateway

Використовуємо таку структуру директорії:

Мінімально необхідний docker-compose.yaml виглядатиме ось так:

version: '3.5'
networks:
  losst-network:
services:
  nginx:
    image: nginx
    ports:
        - '8094:80'
    volumes:
        - ./www/:/var/www/
        - ./conf/nginx:/etc/nginx/conf.d
    networks:
        - losst-network
  php-fpm:
    build: 
      context: ./conf/php-fpm
    extra_hosts:
      host.docker.internal: host-gateway
    volumes:
      - ./www:/var/www/
    networks:
      - losst-network

Ми просто оголошуємо два контейнери, nginx і php-fpm. У перший не вносимо зміни, тому можна просто брати офіційний образ, монтувати папку з вихідними кодами, конфігураційний файл і прокидати порт. У другий контейнер треба встановити і налаштувати Xdebug, тому його доведеться зібрати на основі офіційного контейнера php. Для цього ж контейнера треба вказати директиву extra_hosts, без неї нічого працювати не буде. Конфігурація Nginx теж цілком стандартна:

server {
  listen 80;
  server_name _ !default;
  root /var/www/;
  add_header X-Frame-Options "SAMEORIGIN";
  add_header X-XSS-Protection "1; mode=block";
  add_header X-Content-Type-Options "nosniff";
  index index.html index.htm index.php;
  charset utf-8;
  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }
  error_page 404 /index.php;
  location ~ .php$ {
    fastcgi_pass php-fpm:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    include fastcgi_params;
  }
}

Так налаштовується обробка PHP-скриптів у контейнері php-fpm, і редирект неіснуючих URL на index.php, що цілком стандартно для багатьох фреймворків і CMS. У Dockerfile контейнера php-fpm він має ось такий вигляд:

Встановлюємо xdebug за допомогою pecl, а потім копіюємо його конфігураційний файл у контейнер. Файл:

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = host.docker.internal
xdebug.client_port = 9000

У контейнері встановлено Xdebug 3 для PHP 8, тому що стара версія з цією версією мови вже не працює, тому використовується новий синтаксис конфігурації. Ну і хост, host.docker.internal, який раніше був прописаний у docker-compose.yaml. Налаштування xdebug PHPStorm docker завершено. Далі ви можете запустити проєкт:

docker-compose up --build

Тепер, як і в попередньому варіанті, ви можете увімкнути в браузері режим налагодження, оновити сторінку, і налагоджувальник успішно підключиться до IDE, незважаючи на те, що він працює в Docker