WooCommerce: решение проблемы с незапуском хука woocommerce_order_status_changed

Диагностика проблемы с хуком woocommerce_order_status_changed

Хук woocommerce_order_status_changed — критически важный для разработчиков, которые хотят реагировать на смену статуса заказа. Если этот хук не срабатывает, логика обработки заказов, уведомлений и интеграций может нарушиться.

Основные признаки проблемы:

• Ваш код с добавлением обработчика на woocommerce_order_status_changed не выполняется;
• Письма или действия, завязанные на смену статуса заказа, не отправляются;
• Отсутствие логов или ошибок в debug.log;
• Другие хуки WooCommerce работают корректно.

Проверка подключения обработчика

Для начала проверьте, что обработчик действительно привязан и активен. Добавьте в functions.php вашей темы или в плагин следующий код:

add_action('woocommerce_order_status_changed', function($order_id, $old_status, $new_status, $order) {
    error_log("Order #" . $order_id . " changed from " . $old_status . " to " . $new_status);
}, 10, 4);

Затем совершите смену статуса заказа в админке и проверьте файл wp-content/debug.log. Если запись не появилась, значит хук не срабатывает.

Основные причины и их устранение

1. Несоответствие количества аргументов в обработчике

Хук woocommerce_order_status_changed передаёт 4 аргумента. Если в add_action указать меньше, чем нужно, обработчик не вызовется корректно.

Правильный шаблон:

add_action('woocommerce_order_status_changed', 'my_custom_function', 10, 4);
function my_custom_function($order_id, $old_status, $new_status, $order) {
    // ваш код
}

2. Хук вызывается не при прямом обновлении статуса

Если статус меняется через нестандартные методы (например, напрямую в базе или через сторонние плагины), хук может не запускаться. Рекомендуется менять статус через стандартные методы WooCommerce, например:

$order = wc_get_order($order_id);
$order->update_status('completed');

3. Конфликты с другими плагинами или темой

Отключите все плагины кроме WooCommerce и вашего кода, переключитесь на стандартную тему (например, Storefront), чтобы проверить, срабатывает ли хук. Если да — ищите конфликт.

Пошаговое решение проблемы

1. Включите WP_DEBUG и WP_DEBUG_LOG в wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

2. Добавьте тестовый обработчик на woocommerce_order_status_changed (пример выше) и смените статус заказа через админку.
3. Проверьте wp-content/debug.log на наличие записей.
4. Если записей нет, отключите все сторонние плагины, кроме WooCommerce, и активируйте стандартную тему.
5. Если после этого хук сработает, включайте плагины по одному, чтобы выявить конфликт.
6. Убедитесь, что ваш код использует правильное количество аргументов и приоритеты.

Проверка результата после внедрения

Для проверки исправления:

• Обновите статус заказа в WooCommerce через админку.
• Проверьте наличие записи в wp-content/debug.log с указанным сообщением.
• Убедитесь, что дальнейшие действия, завязанные на хук (отправка писем, интеграции), выполняются.

Частые ошибки и как их исправить

• Неверное количество аргументов в add_action: всегда указывайте четвертый параметр в add_action равным 4 для woocommerce_order_status_changed.
• Использование устаревших методов смены статуса: используйте метод update_status() объекта заказа.
• Вмешательство кэширования: если у вас установлен кэш (например, объектный кэш), временно отключите его для проверки.
• Отсутствие включенного дебага: без WP_DEBUG_LOG трудно отследить проблему.

Практические советы по безопасности и производительности

• Не записывайте лишние данные в лог в продакшн-среде. Используйте дебаг только для отладки.
• Для производительности избегайте тяжелых операций внутри обработчика хука, делайте отложенную обработку через WP Cron.
• При работе с заказами используйте встроенные методы WooCommerce для изменения статуса, чтобы избегать проблем с консистентностью данных.

Сравнение вариантов реализации реакции на смену статуса заказа

add_action('woocommerce_order_status_changed', 'func', 10, 4);

add_action('woocommerce_order_status_completed', 'func');

wp_schedule_single_event(time() + 60, 'my_cron_hook', [$order_id]);