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

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

В WooCommerce статусы заказов управляют логикой обработки покупок — от оформления до доставки. Иногда требуется автоматизировать смену статуса в зависимости от внешних условий, например, после успешной оплаты через нестандартный шлюз или по определённой логике бизнес-процесса. Если автоматическое изменение не срабатывает, нужно проверить регистрацию и корректность обработчика хука woocommerce_order_status_changed.

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

1. Понимание сигнатуры хука

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

• $order_id (int) — ID заказа;
• $old_status (string) — предыдущий статус;
• $new_status (string) — новый статус;
• $order (WC_Order) — объект заказа;
• $order (WC_Order) — объект заказа (в некоторых версиях 3 аргумента, проверьте документацию вашей версии WooCommerce).

В коде подключения функции обработчика важно указать приоритет и количество аргументов:

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

2. Пример: автоматическое переведение заказа в статус "обработан" после оплаты через кастомный шлюз

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

function auto_change_order_status( $order_id, $old_status, $new_status, $order ) {
    // Проверяем, что новый статус — processing
    if ( 'processing' === $new_status ) {
        // Устанавливаем статус completed
        $order->update_status( 'completed', 'Автоматический переход статуса после оплаты через кастомный шлюз.' );
    }
}
add_action( 'woocommerce_order_status_changed', 'auto_change_order_status', 10, 4 );

3. Что нужно учесть при написании обработчика

• Избегайте бесконечных циклов: вызов $order->update_status() снова вызовет хук. Для предотвращения можно добавить флаг или проверять, что новый статус отличается от текущего.
• Проверяйте, что объект $order валиден: if ( ! $order || ! is_a( $order, 'WC_Order' ) ) return;.
• Логируйте события для отладки через error_log() или другие инструменты.

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

После добавления кода:

1. Создайте тестовый заказ и переведите его вручную в статус, который запускает автопереключение (например, processing).
2. Проверьте, что статус автоматически меняется на completed.
3. Проверьте логи ошибок PHP на наличие предупреждений или ошибок.
4. Проверьте, что в административной панели WooCommerce в истории действий заказа появилось ваше сообщение об изменении статуса.

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

• Ошибка: Обработчик хука не вызывается.
  Причина: Неправильное имя функции, неверное количество аргументов в add_action, либо код подключен не в правильном месте (например, не в functions.php или в плагине).
• Ошибка: Заказ не меняет статус, возникает бесконечный цикл.
  Причина: Вызов update_status внутри хука без проверки текущего статуса.
  Решение: Добавьте проверку, чтобы не менять статус, если он уже нужный.
• Ошибка: Ошибка типа при работе с объектом заказа.
  Причина: $order передан не всегда или требует загрузки через wc_get_order($order_id).

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

• Безопасность: Используйте проверку прав пользователя, если обработчик влияет на данные, например, проверяйте current_user_can('edit_shop_orders').
• Производительность: Не вызывайте тяжелые операции внутри хука, таких как запросы к внешним API без асинхронной обработки.
• Логирование: Для продакшена отключайте отладочные логи или отправляйте их в отдельные файлы.

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