Как сделать отладку в WordPress с помощью Xdebug: практическое руководство

Отладка кода — ключевой этап в разработке и сопровождении сайтов на WordPress. Часто стандартных инструментов типа var_dump() или error_log() недостаточно — они не показывают стек вызовов, не позволяют пошагово пройти код и понять, как именно работают функции. В таких случаях на помощь приходит Xdebug — расширение PHP для мощной отладки.

Что такое Xdebug и зачем он нужен в WordPress

Xdebug — это расширение для PHP, которое значительно расширяет возможности отладки и профилирования кода. С его помощью можно:

Поставить точки останова (breakpoints) и пошагово выполнять код
Просматривать значения переменных во время выполнения
Отслеживать стек вызовов функций
Профилировать производительность и выявлять узкие места

В контексте WordPress, где множество хуков, функций и классов, Xdebug помогает быстро понять, почему что-то работает не так, и исправить ошибки без гаданий.

Как установить и настроить Xdebug для WordPress (локальная среда)

Первый шаг — убедиться, что у вас локально установлен PHP с поддержкой Xdebug. Если вы используете популярные среды разработки (например, Laragon, XAMPP, MAMP), Xdebug обычно уже есть, но его нужно активировать.

1. Проверьте наличие Xdebug командой:

php -v

В выводе должна быть строка, содержащая «Xdebug».

2. Если Xdebug не установлен, скачайте его с официального сайта https://xdebug.org и следуйте инструкциям для вашей версии PHP.

3. В php.ini добавьте или отредактируйте настройки:

[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.client_host=127.0.0.1
xdebug.log=/path/to/xdebug.log

Обратите внимание, что порт по умолчанию в Xdebug 3 — 9003, а не 9000.

4. Перезапустите сервер (Apache, Nginx или PHP-FPM).

Интеграция Xdebug с IDE

Для удобной отладки используйте IDE с поддержкой Xdebug, например PhpStorm или Visual Studio Code.

В PhpStorm:

Откройте «Preferences» → «Languages & Frameworks» → «PHP» → «Debug»
Убедитесь, что порт для Xdebug совпадает с настройками php.ini
Настройте сервер, укажите корень вашего WordPress-проекта
Запустите «Listen for PHP Debug Connections»

В Visual Studio Code необходимо установить расширение PHP Debug и настроить launch.json с нужным портом.

Как отлаживать WordPress с Xdebug: практические советы и примеры

Отладка в контексте WordPress имеет свои особенности из-за обилия хуков и фильтров, а также динамического построения страниц. Вот несколько советов:

Отладка хуков и действий

Хуки — это основа расширяемости WordPress, но иногда сложно понять, когда и в каком порядке они вызываются. С Xdebug можно поставить breakpoint в функции, которая подключается к хуку:

add_action('init', 'wplock_debug_init');
function wplock_debug_init() {
    // ваша логика
}

Поставьте breakpoint в wplock_debug_init и запустите отладку — IDE остановится в нужном месте.

Отладка AJAX-запросов WordPress

Для AJAX-запросов важно настроить Xdebug так, чтобы он ловил запросы, приходящие с браузера. Включите в запросе параметр XDEBUG_SESSION или используйте расширения браузера для запуска сессии отладки.

Пример функции с отладкой и логированием

function wplock_get_custom_post_titles() {
    $query = new WP_Query(['post_type' => 'post', 'posts_per_page' => 10]);
    $titles = [];
    while($query->have_posts()) {
        $query->the_post();
        // Поставьте breakpoint на следующей строке для просмотра заголовков
        $titles[] = get_the_title();
    }
    wp_reset_postdata();
    return $titles;
}

Используйте Xdebug, чтобы проверить, как наполняется массив $titles.

Полезные плагины для отладки WordPress

Кроме Xdebug, есть плагины, которые помогают выявлять ошибки и просматривать запросы:

Query Monitor — показывает запросы к базе, ошибки PHP, хуки, HTTP-запросы
Debug Bar — добавляет панель с отладочной информацией в админку
Log Deprecated Notices — логирует использование устаревших функций

Эти плагины хорошо дополняют отладку с помощью Xdebug, особенно если нужно быстро увидеть проблему без запуска IDE.

Частые ошибки при настройке отладки и как их избежать

1. Xdebug не подключается — проверьте, что порт совпадает в php.ini и IDE, а также что Xdebug загружен (phpinfo()).

2. Не срабатывают breakpoint’ы в WordPress — убедитесь, что вы отлаживаете тот же файл, который реально используется (кэш, opcache могут мешать). Отключите кэширование для разработки.

3. Отладка AJAX не работает — проверьте, что сессия отладки активна для AJAX-запросов (параметр XDEBUG_SESSION).

4. Слишком много данных — используйте фильтры для ограничения объема логов и профилирования.