Отладка PHP-проектов с XDebug

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

Краткое описание XDebug

XDebug — это расширение для PHP, предоставляющее развитые средства отладки и аналитики. Он поддерживает удалённую отладку (обычно через протокол DBGp), установку точек останова, пошаговое выполнение кода, просмотр значений переменных, трассировку стека вызовов, профилирование скриптов (Profiling) и формирование отчетов покрытия кода (Coverage). С помощью XDebug разработчик может глубже понять процесс выполнения и состояние кода, что существенно ускоряет поиск и устранение ошибок.

Для повседневной работы чаще всего используется режим debug для интерактивной пошаговой отладки.

Включение и настройка XDebug в ServBay

Во всех поддерживаемых версиях PHP, поставляемых с ServBay, расширение XDebug уже предустановлено. Вам не нужно загружать или компилировать его вручную.

1. Включите модуль XDebug: Откройте интерфейс приложения ServBay. Перейдите в раздел Язык-PHP, выберите версию PHP, для которой требуется XDebug. В списке Расширения найдите модуль xdebug и убедитесь, что его статус — «Включено». Если отключён, нажмите для включения. После этого может потребоваться перезапустить сервис PHP-FPM (обычно ServBay делает это автоматически).

2. Настройте вашу IDE: В вашей интегрированной среде разработки (IDE), например PHPStorm или VS Code, настройте соединение с XDebug. Обычно это включает указание прослушиваемого порта (он должен совпадать с настройками XDebug в UI) и, при необходимости, настройку сопоставления путей (Remote Path Mapping). Однако в локальной среде ServBay эта настройка чаще всего не требуется.

   Подробнее о настройке IDE

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

Практический пример: отладка PHP-проекта в ServBay

Рассмотрим, как использовать XDebug для отладки на простом примере PHP-проекта в среде 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-службой).

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. Установка точки останова

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

4. Запуск отладочной сессии

1. В IDE активируйте прослушивание XDebug-соединений. В PHPStorm это делается кнопкой «Start Listening for PHP Debug Connections» (значок телефонной трубки или жучка на панели инструментов).
2. В браузере перейдите по адресу https://servbay-xdebug-app.servbay.demo/index.php.
3. Если параметр xdebug.start_with_request установлен в trigger, убедитесь, что вы добавили XDebug-триггер через браузерное расширение или вручную (например, посетив URL: https://servbay-xdebug-app.servbay.demo/index.php?XDEBUG_TRIGGER=1).

5. Процесс отладки

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

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): выполнить оставшийся код текущей функции и выйти к месту её вызова.
2. Пошагово исследуйте логику работы кода и отслеживайте изменения в переменных.

8. Продолжение выполнения

1. Для продолжения выполнения до следующего останова или до окончания программы нажмите кнопку «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 можно использовать и для отладки консольных (CLI) PHP-скриптов. Для этого задайте переменные окружения или используйте специальные параметры запуска — подробности ищите в официальной документации XDebug.
• Версия и настройки IDE: Интерфейс и настройка IDE могут отличаться в зависимости от версии; руководствуйтесь официальной документацией вашей среды разработки.

Часто задаваемые вопросы (FAQ)

В: IDE не может подключиться к XDebug, что делать?

О: Проверьте следующее:

1. Убедитесь, что модуль XDebug для используемой версии PHP в ServBay включён.
2. Проверьте параметры xdebug.mode, xdebug.client_host, xdebug.client_port в php.ini — они должны совпадать с настройками IDE.
3. При использовании xdebug.start_with_request = trigger удостоверьтесь, что вы правильно добавили триггер (GET/POST параметр, Cookie или Header).
4. Брандмауэр ОС должен разрешать подключение по порту XDebug.
5. Убедитесь, что IDE действительно прослушивает нужный порт.

В: Почему сайт медленно работает при включённом XDebug?

О: Скорее всего, установлен режим xdebug.start_with_request = yes. Это значит, что каждый PHP-запрос запускает отладку, что влияет на производительность. Рекомендуется переключить параметр в значение trigger и запускать отладку только по необходимости.

В: Можно ли отлаживать AJAX-запросы с помощью XDebug?

О: Да. Отладка AJAX-запросов ничем не отличается от обычных HTTP-запросов — главное, чтобы они тоже содержали XDebug-триггер (например, через Cookie или Header).

В: Работает ли XDebug ServBay только с PHPStorm, или поддерживаются VS Code и другие IDE?

О: Поддерживаются любые IDE и редакторы, совместимые с протоколом DBGp, в частности VS Code (с расширением PHP Debug), NetBeans, Eclipse и др. Настройки аналогичны: требуется указать прослушиваемый порт в настройках IDE.

Заключение

Интеграция XDebug в ServBay позволяет просто и эффективно отлаживать PHP-проекты в локальной среде. Освоив основные приёмы — точки останова, просмотр переменных, пошаговое выполнение — вы быстро находите и исправляете ошибки, повышая качество кода. В комплексе с удобным управлением окружениями от ServBay XDebug становится незаменимым инструментом для любого PHP-разработчика. Начните пользоваться XDebug в ServBay и откройте для себя новые возможности производительной и комфортной PHP-разработки!