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

Что такое хук 'woocommerce_order_status_changed' и когда он срабатывает

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

Хук имеет следующий формат:

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

Где:

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

Диагностика: как проверить, что хук вызывается корректно

Для отладки можно добавить временный обработчик, который будет логировать вызов хука в файл. Например:

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

Затем сделайте смену статуса заказа через админку WooCommerce и проверьте файл wp-content/debug.log (если включён 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 ( 'completed' === $new_status && 'completed' !== $old_status ) {
        $to = $order->get_billing_email();
        $subject = 'Спасибо за покупку!';
        $message = 'Ваш заказ #' . $order_id . ' успешно завершён. Благодарим за выбор нашего магазина.';
        wp_mail( $to, $subject, $message );
    }
}

Код добавьте в файл functions.php вашей дочерней темы или в кастомный плагин.

Как проверить, что решение работает

• Перейдите в админку WooCommerce > Заказы;
• Откройте любой заказ в статусе, отличном от completed;
• Измените статус заказа на completed и сохраните;
• Проверьте почтовый ящик, который указан в заказе, на наличие письма;
• Если письмо не пришло, включите логирование почты с помощью плагина WP Mail Logging и проверьте статус отправки.

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

• Письмо не отправляется — проверьте правильность email клиента и настройку SMTP сервера WordPress;
• Хук не срабатывает — убедитесь, что код подключён (например, в functions.php) и что нет конфликтов с другими плагинами;
• Неверные статусы — помните, что статусы идут без префикса wc-, например, не wc-completed, а completed;
• Отправка письма на каждый статус — добавляйте проверку перехода с одного статуса на другой, чтобы избежать повторных вызовов.

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

• Не выполняйте тяжёлые операции напрямую в хуках — лучше ставьте задачи в очередь (например, с помощью WP Cron или внешних очередей);
• Проверяйте права пользователя, если взаимодействие идёт на фронтенде;
• Используйте проверенные функции WordPress для отправки почты (wp_mail) и не храните чувствительные данные в открытом виде;
• Логируйте ошибки и исключения, чтобы быстро выявлять проблемы при работе кастомных обработчиков.

Сравнение способов обработки смены статуса заказа