Как использовать хук action WooCommerce для обработки смены статуса заказа

Диагностика задачи: зачем обрабатывать смену статуса заказа в WooCommerce

В WooCommerce смена статуса заказа — ключевое событие для автоматизации процессов: отправки уведомлений, обновления внешних систем, запуска отгрузки и т.п. Часто требуется выполнить кастомный код именно в момент изменения статуса, например, когда заказ переходит из "в обработке" в "завершён" или "отменён". Для этого используется хук woocommerce_order_status_changed.

Пошаговое решение: как правильно использовать хук woocommerce_order_status_changed

Хук woocommerce_order_status_changed вызывается с четырьмя параметрами:

• $order_id — ID заказа
• $old_status — старый статус заказа
• $new_status — новый статус заказа
• $order — объект WC_Order

Пример базового кода для отслеживания смены статуса заказа и запуска кастомной функции:

add_action('woocommerce_order_status_changed', 'custom_handle_order_status_change', 10, 4);
function custom_handle_order_status_change($order_id, $old_status, $new_status, $order) {
    // Проверяем переход из 'processing' в 'completed'
    if ($old_status === 'processing' && $new_status === 'completed') {
        // Ваш кастомный код, например, отправка письма
        error_log("Заказ #{$order_id} завершён, запускаем кастомный процесс.");
        // Допустим, вызов функции отправки уведомления
        send_custom_notification($order);
    }
}

function send_custom_notification($order) {
    $to = $order->get_billing_email();
    $subject = 'Ваш заказ завершён';
    $message = 'Спасибо за покупку! Ваш заказ #' . $order->get_id() . ' успешно завершён.';
    wp_mail($to, $subject, $message);
}

Как добавить обработку нескольких переходов статусов

Если нужно отследить разные статусы, стоит использовать условные операторы или switch:

add_action('woocommerce_order_status_changed', 'handle_multiple_status_changes', 10, 4);
function handle_multiple_status_changes($order_id, $old_status, $new_status, $order) {
    switch ("{$old_status}_to_{$new_status}") {
        case 'pending_to_processing':
            // Действия при переходе из 'pending' в 'processing'
            break;
        case 'processing_to_completed':
            // Действия при переходе из 'processing' в 'completed'
            break;
        case 'on-hold_to_cancelled':
            // Действия при переходе из 'on-hold' в 'cancelled'
            break;
    }
}

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

Чтобы проверить, что ваш код сработал, сделайте следующее:

• Включите запись логов ошибок PHP / WooCommerce (WP_DEBUG_LOG в wp-config.php).
• Используйте error_log внутри вашей функции для отладки.
• Измените статус заказа вручную в админке WooCommerce и проверьте, появляется ли соответствующая запись в логе.
• Если отправляете письма, проверьте почтовый ящик заказчика или логи почтового сервера.

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

• Неправильное количество аргументов в add_action: Хук woocommerce_order_status_changed передаёт 4 параметра, не забудьте указать 4 в последнем аргументе add_action, иначе получите ошибку или неработающий код.
• Использование устаревших статусов: Статусы заказа в WooCommerce строго определены (например, pending, processing, completed, cancelled). Проверьте, что пишете их в нижнем регистре и без опечаток.
• Отсутствие проверки объекта заказа: Иногда полезно проверить, что $order — это экземпляр WC_Order, чтобы избежать ошибок, особенно если вызов происходит из нестандартного контекста.
• Конфликты с другими плагинами: Если код не срабатывает, попробуйте временно отключить сторонние плагины, которые также могут работать со статусами заказов.

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

• Минимизируйте нагрузку в обработчике: Хук вызывается при каждом изменении заказа, не выполняйте тяжелые операции напрямую. Лучше ставьте задачи в очередь или используйте WP Cron.
• Фильтруйте статусы: Выполняйте действия только при нужных статусах, чтобы избежать лишних вызовов.
• Проверяйте права: Если код отправляет письма или обновляет данные, убедитесь, что он не может быть вызван злоумышленником через AJAX или REST без авторизации.

Сравнение вариантов реализации