Як увімкнути та налаштувати модуль Xdebug у ServBay

ServBay — це потужне локальне середовище веб-розробки, яке вже містить інтегрований інструмент Xdebug для відладки й профілювання PHP. Включення Xdebug може суттєво підвищити ефективність розробки PHP додатків, допоможе зручніше знаходити помилки, аналізувати продуктивність і перевіряти покриття коду тестами. У цій статті докладно описано, як увімкнути та налаштувати Xdebug у ServBay, а також інструкції щодо інтеграції з провідними середовищами розробки (IDE).

Огляд модуля Xdebug

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

Основні можливості Xdebug

Відладка з точками зупинки: Дає змогу зупиняти виконання коду на вибраних рядках, щоб переглянути поточний стан змінних, стек викликів тощо, і виконувати код покроково.
Покрокова відладка: Доступні операції "Step Over", "Step Into", "Step Out" для детального відстеження виконання програми.
Моніторинг змінних: Перегляд значень локальних та глобальних змінних у режимі реального часу під час відладки.
Трасування стеку викликів: У разі помилок чи винятків Xdebug надає детальну інформацію про виклики функцій для швидкої локалізації джерела проблеми.
Профілювання продуктивності (Profiling): Генерує звіти по продуктивності виконання коду, що дозволяє ідентифікувати вузькі місця.
Перевірка покриття коду (Code Coverage): Вимірює, яку частину коду покривають тести, що допомагає оцінити повноту тестування.

Вбудовані версії Xdebug і відповідність портів у ServBay

ServBay постачається з попередньо встановленими модулями Xdebug для різних версій PHP. Зверніть увагу: кожній версії PHP відповідає окремий порт для Xdebug, порт прив'язаний до версії PHP. Це важливо для правильного налаштування відладки у вашій IDE.

Версія PHP	Вбудована версія Xdebug	Типовий порт Xdebug
PHP 5.6	Xdebug 2.5.5	39056
PHP 7.0	Xdebug 2.5.5	39070
PHP 7.1	Xdebug 2.5.5	39071
PHP 7.2	Xdebug 3.1.6	39072
PHP 7.3	Xdebug 3.1.6	39073
PHP 7.4	Xdebug 3.1.6	39074
PHP 8.0	Xdebug 3.3.1	39080
PHP 8.1	Xdebug 3.4.0	39081
PHP 8.2	Xdebug 3.4.0	39082
PHP 8.3	Xdebug 3.4.0	39083
PHP 8.4	Xdebug 3.4.0	39084
PHP 8.5	Xdebug 3.4.0	39085

Правило портів

Правило для типового порту Xdebug таке: 39000 + додатковий номер версії PHP. Наприклад, для PHP 8.3 порт буде 39000 + 83 = 39083, для PHP 7.4 — 39000 + 74 = 39074. Це дозволяє швидко визначати порт Xdebug для потрібної версії PHP.

Як увімкнути модуль Xdebug

Активація Xdebug у ServBay дуже проста — рекомендуємо використовувати графічний інтерфейс користувача (GUI), але це можливо і через ручне редагування конфігураційних файлів.

Увімкнення Xdebug через GUI ServBay

Це найшвидший і найзручніший спосіб.

Відкрийте інтерфейс додатку ServBay.
У лівому меню виберіть Мови (Languages).
Розгорніть розділ PHP і знайдіть потрібну версію PHP, наприклад, PHP 8.3.
Натисніть кнопку Розширення навпроти вибраної версії.
У вікні списку розширень відшукайте модуль Xdebug.
Переведіть перемикач ліворуч від Xdebug у положення "Увімкнено".
За потреби змініть параметри.
Натисніть Зберегти унизу сторінки.
ServBay автоматично перезапустить процес PHP і підключить модуль.

Ілюстрація: Включення Xdebug в меню розширень

Як перевірити, чи Xdebug успішно підключено

Найнадійніше перевірити це через функцію phpinfo() і перегляд інформації про конфігурацію PHP.

У корені сайту ServBay (типово /Applications/ServBay/www) створіть файл, наприклад, phpinfo.php.
Додайте в цей файл такий вміст:
php
```
<?php
phpinfo();
?>
```
1
2
3
Відкрийте цей файл у браузері, наприклад, https://servbay.demo/phpinfo.php (замініть servbay.demo на вашу локальну адресу).
На сторінці виводу phpinfo знайдіть "Xdebug". Якщо модуль Xdebug підключено коректно — ви побачите окремий блок конфігурації Xdebug з даними про версію й параметри.

Ілюстрація: Розділ Xdebug у виводі phpinfo

Налаштування Xdebug для відладки у IDE

Ввімкнути Xdebug — лише перший крок. Для відладки з точками зупинки знадобиться додаткове налаштування у IDE: вибір PHP-інтерпретатора, порту та конфігурації мапінгу шляхів. Нижче описано кроки для PHPStorm та Visual Studio Code (VS Code).

Налаштування Xdebug у PHPStorm

PHPStorm має повноцінну інтеграцію з Xdebug.

Відкрийте налаштування PHPStorm: Стартуйте PHPStorm, і відкрийте налаштування через меню File -> Settings (Windows/Linux) або PHPStorm -> Preferences (macOS).
Налаштуйте PHP CLI інтерпретатор:
- Перейдіть до Languages & Frameworks -> PHP.
- У секції CLI Interpreter натисніть ....
- У вікні натисніть +, щоб додати новий локальний інтерпретатор.
- Вкажіть шлях до виконуваного PHP у ServBay, наприклад /Applications/ServBay/package/php/8.3/8.3.7/bin/php (зверніть увагу на версію у вашій системі).
- PHPStorm сам визначить версію і підключені розширення, включаючи Xdebug.
- Натисніть OK для збереження. Ілюстрація: Налаштування CLI інтерпретатора PHP у PHPStorm для ServBay
Налаштування параметрів Xdebug:
- Відкрийте Languages & Frameworks -> PHP -> Debug.
- У секції Xdebug виставте Debug Port згідно з версією PHP у ServBay (наприклад, для PHP 8.3 — 39083). Він має збігатися з налаштуванням xdebug.client_port.
- Позначте Can accept external connections.
- Натисніть Apply та OK. Ілюстрація: Вибір порту Xdebug у PHPStorm
Мапінг веб-серверів у PHPStorm:
- Перейдіть у Languages & Frameworks -> PHP -> Servers.
- Додайте новий сервер (+), вкажіть назву, наприклад, ServBay Localhost.
- Заповніть Host адресою сайту в ServBay (наприклад, servbay.demo).
- Порт — той, що використовується сайтом (443 для HTTPS або 80 для HTTP).
- Виберіть відладчик Xdebug.
- Позначте Use path mappings.
- Встановіть відповідність шляху проекту на вашому комп’ютері та шляху на сервері (наприклад, /Applications/ServBay/www/myproject → /, якщо доступ через https://servbay.demo/). Для піддоменів — аналогічно, слідкуйте за відповідністю шляху!
- Натисніть OK. Ілюстрація: Сервери та мапінги шляхів у PHPStorm
Запуск відладки:
- Відкрийте файл проєкту у PHPStorm.
- Поставте точку зупинки (клік по рядку коду ліворуч).
- На верхній панелі PHPStorm натисніть Start Listening for PHP Debug Connections (значок жучка). Значок стане зеленим — IDE слухає підключення Xdebug.
- Відкрийте застосунок PHP у браузері (наприклад, https://servbay.demo/index.php).
- Якщо все налаштовано правильно, Xdebug здійснить підключення до PHPStorm і зупинить виконання на точці зупинки. Ілюстрація: Запуск очікування підключення Xdebug у PHPStorm

Налаштування Xdebug у Visual Studio Code (VS Code)

VS Code — популярний редактор коду, який також підтримує Xdebug через розширення.

Встановіть розширення PHP Debug:
- Відкрийте VS Code.
- В панелі розширень (Ctrl+Shift+X або Cmd+Shift+X) знайдіть "PHP Debug" (автор Felix Becker) і встановіть.

Налаштуйте launch.json:

Відкрийте папку PHP-проекту.
Відкрийте вкладку "Run and Debug" (Ctrl+Shift+D або Cmd+Shift+D).
Натисніть значок шестерні і виберіть "PHP" — це створить файл launch.json у .vscode всередині проекту.
Відредагуйте launch.json, щоб параметр port відповідав портові Xdebug для вашої версії PHP у ServBay (наприклад, 39083 для PHP 8.3).

Налаштуйте мапінг шляхів (pathMappings): ця опція є ключовою для відладки у VS Code. Вкажіть відповідність шляху на сервері та локального шляху до проекту.

json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 39083, // За потреби змініть порт згідно з версією PHP
            "pathMappings": {
                // Вказати відповідність кореня сайту ServBay і локальної папки проекту
                "/": "${workspaceRoot}"
            }
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 39083 // За потреби змініть порт згідно з версією PHP
        }
    ]
}

Відкоригуйте pathMappings залежно від структури проекту і налаштувань у ServBay. ${workspaceRoot} — це корінь відкритої вами у VS Code папки.

Запуск відладки:
- Відкрийте потрібний PHP-файл у VS Code.
- Поставте точку зупинки (клік ліворуч від рядка).
- Перейдіть на вкладку запуску відладки (Ctrl+Shift+D або Cmd+Shift+D).
- У випадаючому списку виберіть "Listen for Xdebug".
- Натисніть зелену кнопку старту. Статусбар VS Code стане помаранчевим — йде слухання підключень Xdebug.
- Відкрийте ваш PHP-додаток у браузері. Якщо налаштування вірні, Xdebug підключиться до VS Code і виконає зупинку на точці зупинки.

Часті питання (FAQ)

Q: Xdebug не відображається у phpinfo()?
- A: Переконайтеся, що ви активували Xdebug через GUI ServBay або вручну у файлі xdebug.ini.
- Перезапустіть відповідний PHP-сервіс.
- Перевірте правильність шляху до xdebug.ini і переконайтеся, що рядок zend_extension = xdebug.so не закоментований.
- Ознайомтесь з логами ServBay (/Applications/ServBay/logs/php/<version>/error.log) на предмет помилок завантаження Xdebug.
Q: Програма не зупиняється на точках у IDE?
- A: Переконайтеся, що IDE слухає підключення (у PHPStorm жучок зелений, а у VS Code статус-панель помаранчева).
- Перевірте, чи порт Xdebug у IDE відповідає параметру xdebug.client_port і port для відповідної версії PHP у ServBay.
- Правильно налаштований мапінг шляхів між сервером і вашим проектом у IDE — це найчастіша причина проблем.
- Перевірте налаштування фаєрволу: порт Xdebug має бути відкритий (стандартно це серія портів 390xx).
- Якщо у xdebug.ini використовується параметр xdebug.start_with_request=trigger, переконайтеся, що у браузері/запиті є тригер (наприклад, розширення Xdebug у браузері або додати в URL ?XDEBUG_TRIGGER=1).
Q: Xdebug відключається через певний час?
- A: Перевірте параметри xdebug.remote_autostart або xdebug.start_with_request у xdebug.ini. Значення yes може спричиняти запуск відладки для кожного запиту; рекомендується режим trigger.
- Перевірте таймаути на стороні IDE.

Висновок

ServBay робить процес налаштування й використання Xdebug максимально простим завдяки попередньо встановленим модулям та зручному GUI. Всього за кілька кліків, або через пряме редагування конфігурації, ви зможете швидко активувати Xdebug для будь-якої версії PHP у ServBay. Із потужними можливостями PHPStorm, VS Code та інших IDE вам стане доступна глибока відладка, профілювання продуктивності і контроль якості коду. Поєднання ServBay із Xdebug — справжній must-have для будь-якого розробника PHP на локальній машині.

Як увімкнути та налаштувати модуль Xdebug у ServBay ​

Огляд модуля Xdebug ​

Основні можливості Xdebug ​

Вбудовані версії Xdebug і відповідність портів у ServBay ​

Як увімкнути модуль Xdebug ​

Увімкнення Xdebug через GUI ServBay ​

Як перевірити, чи Xdebug успішно підключено ​

Налаштування Xdebug для відладки у IDE ​

Налаштування Xdebug у PHPStorm ​

Налаштування Xdebug у Visual Studio Code (VS Code) ​

Часті питання (FAQ) ​

Висновок ​