Как использовать хук action WooCommerce order status changed для кастомных действий

Что такое хук action WooCommerce order status changed и где его применять

В WooCommerce часто требуется запускать дополнительные процессы при изменении статуса заказа. Например, отправить кастомное уведомление, обновить внешнюю систему учета или изменить пользовательские метаданные заказа. Для этих задач существует хук action woocommerce_order_status_changed, который срабатывает при любом изменении статуса заказа.

Его сигнатура выглядит так:

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.

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

Если вы добавили обработчик на woocommerce_order_status_changed, но не видите нужных действий — проверьте:

• Подключен ли ваш код (например, в functions.php темы или в кастомном плагине);
• Срабатывает ли вообще хук, можно добавить логирование;
• Соответствуют ли статусы, которые вы проверяете, реальным значениям статусов заказа.

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

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

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

Пошаговое решение: как добавить кастомное действие при смене статуса заказа

Допустим, нужно отправить письмо клиенту, когда заказ переходит в статус processing.

1. Добавьте следующий код в файл functions.php вашей темы или в кастомный плагин:

add_action( 'woocommerce_order_status_changed', 'custom_order_status_processing_action', 10, 4 );
function custom_order_status_processing_action( $order_id, $old_status, $new_status, $order ) {
    if ( 'processing' === $new_status ) {
        $to = $order->get_billing_email();
        $subject = 'Ваш заказ в обработке';
        $message = 'Здравствуйте! Ваш заказ #' . $order_id . ' сейчас в статусе обработки.';
        wp_mail( $to, $subject, $message );
    }
}

Сохраните изменения.

Перейдите в админку WooCommerce и измените статус заказа на processing.

Проверьте почту, указанную в заказе.

Другие примеры кастомных действий

• Обновление метаданных заказа:

add_action( 'woocommerce_order_status_changed', function( $order_id, $old_status, $new_status, $order ) {
    if ( 'completed' === $new_status ) {
        $order->update_meta_data( '_custom_completed_date', current_time( 'mysql' ) );
        $order->save();
    }
}, 10, 4 );

• Отправка webhook в внешнюю систему:

add_action( 'woocommerce_order_status_changed', function( $order_id, $old_status, $new_status, $order ) {
    $webhook_url = 'https://example.com/webhook';
    $response = wp_remote_post( $webhook_url, [
        'body' => json_encode([
            'order_id' => $order_id,
            'old_status' => $old_status,
            'new_status' => $new_status,
        ]),
        'headers' => [ 'Content-Type' => 'application/json' ],
    ]);
}, 10, 4 );

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

• Включите режим отладки WordPress (define('WP_DEBUG', true); define('WP_DEBUG_LOG', true); в wp-config.php).
• Добавьте логирование в обработчик, как показано в блоке диагностики.
• Измените статус заказа через админку WooCommerce.
• Проверьте почту, логи и/или внешние сервисы, если используете webhook.

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

• Не подключен код: функция добавлена не в активную тему или плагин.
• Неправильные статусы: используйте правильные статусы заказа. Список можно получить через wc_get_order_statuses().
• Ошибка в параметрах функции: хук принимает 4 параметра, укажите их все и правильный приоритет (обычно 10).
• Отсутствие проверки статуса: обработчик срабатывает на любые статусы — всегда проверяйте $new_status.
• Проблемы с почтой: убедитесь, что wp_mail() работает корректно на сервере (тест через wp_mail отдельно).

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

• Не запускайте тяжелые операции напрямую в обработчике — используйте wp_schedule_single_event для отложенного выполнения.
• При отправке webhook ставьте таймауты и обрабатывайте ошибки wp_remote_post.
• Для отправки писем используйте SMTP-сервер или специализированные плагины для надежной доставки.
• Ограничьте количество вызываемых действий, чтобы не замедлять работу админки и фронтенда.

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

Способ	Преимущества	Недостатки	Когда использовать
Хук woocommerce_order_status_changed	Прямой доступ к заказу, простой код, гибкость	Все действия выполняются синхронно, может замедлить процесс	Небольшие быстрые задачи, отправка писем, обновление метаданных
Отложенное событие через wp_schedule_single_event	Не блокирует основной поток, можно повторять задачи	Сложнее в реализации, требует cron	Тяжелые операции, интеграции с внешними сервисами
Плагины автоматизации (например, WPShop Clearfy Pro)	Интерфейс, готовые решения, поддержка	Зависимость от стороннего кода, ограниченная гибкость	Быстрое внедрение, стандартные задачи