Использование хука woocommerce_order_status_changed для кастомных действий при смене статуса заказа

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

В стандартной установке WooCommerce вы можете столкнуться с задачей выполнить определённые действия, когда заказ меняет статус, например, отправить дополнительное уведомление, записать данные в стороннюю систему или изменить пользовательские метаданные. При этом важно делать это без нарушения работы ядра и плагинов WooCommerce.

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

Что такое хук woocommerce_order_status_changed и как он работает

Хук woocommerce_order_status_changed вызывается каждый раз, когда заказ меняет статус. Он передаёт четыре параметра:

• $order_id — ID заказа;
• $old_status — старый статус (например, 'pending');
• $new_status — новый статус (например, 'completed');
• $order — объект WC_Order.

Таким образом, вы можете однозначно отследить, какой заказ и как изменился, и запустить нужные действия.

Пошаговое решение: добавляем свою логику при смене статуса

1. Подключение к хуку

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

2. Реализация функции обработчика

function custom_order_status_change_handler($order_id, $old_status, $new_status, $order) {
    // Пример: при смене статуса на completed отправляем кастомное письмо
    if ($new_status === 'completed') {
        $to = $order->get_billing_email();
        $subject = 'Спасибо за покупку!';
        $message = 'Ваш заказ #' . $order_id . ' успешно завершён.';
        wp_mail($to, $subject, $message);
    }
    // Можно добавить другие условия и действия
}

3. Размещение кода

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

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

Чтобы убедиться, что ваш код работает:

• Создайте тестовый заказ в WooCommerce;
• Измените статус заказа вручную в админке, например, на completed;
• Проверьте, пришло ли письмо на указанный email;
• Для отладки можно добавить логирование в файл через error_log():

error_log('Статус заказа #' . $order_id . ' изменён с ' . $old_status . ' на ' . $new_status);

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

• Неверный приоритет или количество аргументов в add_action: убедитесь, что вы указали именно 4 аргумента, иначе параметры в функцию не попадут.
• Отправка почты не работает: проверьте конфигурацию почты на сервере, используйте SMTP-плагины для надёжности.
• Код добавлен в родительскую тему и теряется после обновления: всегда используйте дочернюю тему или кастомный плагин.
• Перегрузка сервера из-за тяжёлых операций при каждом изменении статуса: избегайте сложных синхронных действий, применяйте очереди или асинхронные вызовы.

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

• Проверяйте, что $order — валидный объект WC_Order, чтобы избежать ошибок.
• Не вызывайте внешние API синхронно в обработчике, лучше использовать wp_cron или очередь задач.
• Минимизируйте выполнение кода, проверяя статусы, чтобы не запускать действия без нужды.

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

Метод	Плюсы	Минусы
Использование woocommerce_order_status_changed	Простой, надежный, вызывается всегда при смене статуса	Требует базовых навыков PHP, возможна перегрузка при тяжёлых операциях
Перехват статуса в шаблонах или AJAX	Легко отлаживать, удобно для UI-логики	Не подходит для фоновых операций, не всегда вызывается
Использование сторонних плагинов автоматизации	Готовые решения, часто с UI	Меньше гибкости, зависимость от сторонних обновлений