Налагодження PHP-проєктів з XDebug

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

Коротко про XDebug

XDebug — розширення, розроблене для PHP, яке пропонує потужні можливості налагодження й аналізу програм. Воно підтримує віддалене налагодження (зазвичай через протокол DBGp), встановлення брейкпоінтів, покрокове виконання, перевірку значення змінних, відстеження стека викликів, профілювання скриптів (Profiling), а також генерацію звітів про покриття коду (Coverage). Завдяки XDebug розробники можуть глибоко розуміти виконання коду, пришвидшуючи процес локалізації та вирішення проблем.

XDebug підтримує кілька режимів роботи, з яких найпоширенішим є режим debug для інтерактивного налагодження з брейкпоінтами.

Активація та налаштування XDebug у ServBay

У кожній із підтримуваних ServBay версій PHP XDebug вже встановлений за замовчуванням. Завантаження або компіляція вручну не потрібні.

1. Увімкнення модуля XDebug: Запустіть інтерфейс програми ServBay. Перейдіть до розділу Мови → PHP, знайдіть версію PHP, для якої потрібно використати XDebug. У вкладці Розширення знайдіть модуль xdebug і переконайтеся, що він активований. Якщо модуль вимкнений — натисніть для активації. Після ввімкнення може знадобитися перезапустити сервіс PHP-FPM (у більшості випадків ServBay зробить це автоматично).

2. Налаштування вашого IDE: У вашій інтегрованій середовищі розробки (IDE), наприклад PHPStorm чи VS Code, налаштуйте підключення XDebug. Зазвичай це передбачає виставлення порту для прослуховування (має відповідати налаштуванням XDebug у ServBay) та, за необхідності, мапінгу шляхів (у типових локальних проєктах на ServBay це не потрібно).

   Докладніше про налаштування IDE

   Детальні кроки з підключення XDebug у конкретних IDE (PHPStorm, VS Code тощо) дивіться в офіційній документації відповідних середовищ або у статті Як увімкнути Xdebug у ServBay.

Практичний приклад: налагодження PHP-проєкту у ServBay

Давайте розглянемо покроково, як використовувати XDebug у ServBay для налагодження простого проєкту.

1. Створення сайту у ServBay

Спершу створіть у ServBay новий сайт, куди розмістите тестовий проєкт:

1. У корені сайтів ServBay /Applications/ServBay/www/ створіть нову папку, наприклад servbay-xdebug-app.
2. Відкрийте програму ServBay та перейдіть у розділ “Сайти”.
3. Натисніть “Додати сайт” і вкажіть шлях до кореня: /Applications/ServBay/www/servbay-xdebug-app.
4. Встановіть локальний домен, наприклад servbay-xdebug-app.servbay.demo.
5. Оберіть версію PHP, переконайтеся, що для неї вже увімкнено і налаштовано XDebug (див. кроки вище).
6. Збережіть і застосуйте зміни. ServBay автоматично сконфігурує Caddy/Nginx і оновить файл hosts (або використає DNS від ServBay).

2. Структура та код прикладного проєкту

У директорії /Applications/ServBay/www/servbay-xdebug-app/ створіть такі файли та папки:

servbay-xdebug-app/
├── src/
│   └── Calculator.php
└── index.php

Вміст файлу src/Calculator.php:

<?php
namespace App;

class Calculator
{
    public function add($a, $b)
    {
        // Встановіть брейкпоінт на цьому рядку
        return $a + $b;
    }

    public function subtract($a, $b)
    {
        return $a - $b;
    }
}

Вміст файлу index.php:

<?php
// Припустимо, ви використовуєте Composer, тут підключається автозавантажувач
// Якщо Composer не використовується, змініть підключення згідно вашого проєкту
require __DIR__ . '/vendor/autoload.php';

use App\Calculator;

echo "Debugging Example:\n";

$calculator = new Calculator();
$num1 = 5;
$num2 = 3;

$sum = $calculator->add($num1, $num2);
$difference = $calculator->subtract($num1, $num2);

echo "Sum: " . $sum . "\n";
echo "Difference: " . $difference . "\n";

echo "Done.\n";
?>

Зверніть увагу: Використання require __DIR__ . '/vendor/autoload.php'; припускає, що ви працюєте з Composer. Для простого тесту достатньо видалити цей рядок і змінити use App\Calculator; на require __DIR__ . '/src/Calculator.php';.

3. Встановлення брейкпоінту

Відкрийте файл /Applications/ServBay/www/servbay-xdebug-app/src/Calculator.php у вашому IDE (наприклад, PHPStorm). Поставте брейкпоінт біля рядка return $a + $b; у методі add.

4. Запуск сесії налагодження

1. Активуйте у своєму IDE режим прослуховування XDebug-з'єднань. У PHPStorm це кнопка “Start Listening for PHP Debug Connections” на панелі інструментів (значок телефонної трубки або жука).
2. Відвідайте у браузері сторінку index.php свого сайту у ServBay: https://servbay-xdebug-app.servbay.demo/index.php.
3. Якщо у вас xdebug.start_with_request встановлено у trigger, переконайтеся, що ви увімкнули XDebug-тригер через розширення браузера або вручну (наприклад, через https://servbay-xdebug-app.servbay.demo/index.php?XDEBUG_TRIGGER=1).

5. Процес налагодження

1. Після звернення до index.php і спрацювання XDebug, розширення підключиться до вашого IDE і зупинить виконання на вказаному брейкпоінті.
2. IDE переключиться у режим дебагу і покаже, що виконання призупинено у файлі Calculator.php на рядку з брейкпоінтом у методі add.

6. Перевірка змінних

1. У вікні налагодження IDE буде видно поточний виконуваний рядок, стек викликів (Call Stack), значення змінних (Variables).
2. На вкладці “Variables” ви побачите локальні змінні: наприклад, $a повинно дорівнювати 5, $b — 3.

7. Покрокове виконання

1. Користуйтеся кнопками покрокового виконання IDE (зазвичай це Step Over (F8), Step Into (F7), Step Out (Shift+F8)):
   • Step Over: виконує поточний рядок без входу у функцію, якщо та викликається.
   • Step Into: входить усередину виклику функції для покрокового перегляду.
   • Step Out: завершує виконання поточної функції й повертається на рівень вище.
2. Так ви можете уважно простежити зміну логіки та значення змінних у вашому коді.

8. Продовження виконання

1. Натисніть у IDE кнопку “Resume Program” (як правило, зелена іконка відтворення чи клавіша F9) — виконання триватиме до наступного брейкпоінта або завершення скрипту.

9. Перегляд результату

1. Після завершення виконання перегляньте результат у браузері (чи у консольному виводі, якщо налагодження CLI-скриптів). У цьому прикладі побачите:

   Debugging Example:
   Sum: 8
   Difference: 2
   Done.

Корисні поради

• Фаєрвол: Перевірте, чи ваш системний фаєрвол не блокує порт, який прослуховує ваше IDE (стандартно 9003).
• Конфлікт портів: Переконайтеся, що порт, налаштований для XDebug, не зайнятий іншою програмою.
• Вплив на продуктивність: Якщо встановити xdebug.mode=debug та xdebug.start_with_request=yes, усі PHP-запити запускають налагодження, що значно уповільнює сайт. Увімкніть XDebug або активуйте xdebug.start_with_request=trigger лише за потреби.
• CLI-налагодження: XDebug можна застосовувати також для налагодження PHP-CLI скриптів. Для цього слід задати змінні оточення чи параметри запуску — див. офіційну документацію XDebug.
• Версії IDE і налаштування: Інтерфейси та поведінка різних IDE можуть відрізнятися — орієнтуйтеся на офіційну документацію вашого редактора для коректних налаштувань.

Поширені запитання (FAQ)

Q: IDE не підключається до XDebug — що робити?

A: Перевірте наступне:

1. Чи увімкнено XDebug у зазначеній версії PHP у ServBay.
2. Чи правильно налаштовано у php.ini параметри xdebug.mode, xdebug.client_host, xdebug.client_port, і чи збігаються вони з налаштуваннями IDE.
3. Якщо використовується xdebug.start_with_request = trigger, переконайтеся, що тригер передається правильно (GET/POST параметр, Cookie, Header).
4. Чи не блокує фаєрвол порт XDebug.
5. Чи дійсно IDE прослуховує потрібний порт.

Q: Чому мій сайт стає повільним після увімкнення XDebug?

A: Ймовірно, тому що активовано xdebug.start_with_request=yes. У цьому режимі кожен PHP-запит запускає сесію дебагу, що значно навантажує додаток. Радимо переключити цей параметр у режим trigger та активувати XDebug лише за потреби.

Q: Чи можна налагоджувати AJAX-запити через XDebug?

A: Так. Налагодження AJAX-запитів аналогічне звичайним HTTP-запитам, лише слід переконатися, що XDebug-тригер передається також (наприклад, через Cookie чи Header).

Q: Чи підтримується XDebug у VS Code або інших IDE окрім PHPStorm у ServBay?

A: Так. XDebug, інтегрований до ServBay, є стандартним PHP-розширенням і працює з будь-якою IDE чи редактором, що підтримує протокол DBGp, зокрема з VS Code (з розширенням PHP Debug), NetBeans, Eclipse тощо. Процедура підключення аналогічна: основне — правильно налаштуйте порт прослуховування.

Висновок

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