WooCommerce: использование хука woocommerce_order_status_changed для автоматизации процессов

Что такое хук woocommerce_order_status_changed и зачем он нужен

Хук woocommerce_order_status_changed срабатывает при изменении статуса заказа в WooCommerce. Он передаёт три параметра: ID заказа, старый статус и новый статус. Это позволяет запускать кастомные скрипты в момент перехода заказа, например, отправлять уведомления, менять метаданные, интегрировать с CRM или другими системами.

Сигнатура хука

do_action( 'woocommerce_order_status_changed', $order_id, $old_status, $new_status, $order );

Обратите внимание, начиная с WooCommerce 3.0, четвёртым параметром передаётся объект заказа WC_Order.

Диагностика: когда и как применяется хук

Если у вас не работает автоматизация, основанная на смене статуса заказа, нужно проверить несколько моментов:

• Правильность регистрации функции на хук.
• Используете ли вы правильные статусы заказа (processing, completed, cancelled и т.д.).
• Выполняется ли код только при нужном переходе статуса.
• Совместимость с версией WooCommerce.

Для проверки добавьте простой лог для отладки:

add_action('woocommerce_order_status_changed', function($order_id, $old_status, $new_status) {
    error_log("Заказ #$order_id изменил статус с $old_status на $new_status");
}, 10, 3);

После смены статуса проверьте файл debug.log в папке wp-content (если включён WP_DEBUG_LOG).

Пошаговое решение: автоматическая отправка кастомного письма при смене статуса на «completed»

Пример: отправим письмо администратору, когда заказ становится выполненным.

add_action('woocommerce_order_status_changed', 'send_custom_email_on_completed', 10, 4);
function send_custom_email_on_completed($order_id, $old_status, $new_status, $order) {
    if ($new_status === 'completed' && $old_status !== 'completed') {
        $to = get_option('admin_email');
        $subject = "Заказ #$order_id выполнен";
        $message = "Заказ #$order_id был успешно выполнен. Проверьте детали в админке.";
        wp_mail($to, $subject, $message);
    }
}

Обратите внимание, что проверка $old_status !== 'completed' предотвращает повторную отправку, если статус меняется на тот же.

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

• Создайте тестовый заказ в WooCommerce с любым статусом.
• В админке измените статус заказа на «completed».
• Проверьте, что письмо отправилось (например, через почтовый сервер или логирование).
• Проверьте debug.log на наличие отладочных сообщений, если вы их добавляли.

Частые ошибки при использовании хука woocommerce_order_status_changed

• Неправильное количество аргументов в функции обратного вызова. Хук передаёт 4 аргумента, поэтому при регистрации укажите 4 параметра и параметр accepted_args в add_action равным 4.
• Сравнение статусов без кавычек или с неправильными именами. Статусы — это строки в нижнем регистре, например, completed, pending.
• Отсутствие проверки старого статуса. Без неё можно получить много лишних срабатываний.
• Отправка писем без настройки SMTP. Рекомендуется использовать SMTP-плагин или сервис, чтобы письма не попадали в спам.

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

• Избегайте тяжёлых операций напрямую в хуках, особенно при массовом обновлении заказов — используйте отложенные задачи через wp_cron или внешние очереди.
• Проверяйте права доступа и валидность данных, если используете ID заказа или данные из объекта WC_Order.
• Для логирования используйте error_log или специализированные логгеры, отключайте их в продакшене.

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