Состояния заказа

Состояние заказа показывает, на каком этапе он находится: ждёт оплаты, оплачен, отправлен. WooCommerce меняет состояние сам при оплате, а менеджер — вручную в панели. Каждая смена вызывает хук, и на нём строят автоматику: передать заказ на склад, отправить сообщение.

Стандартные состояния

Смена состояния

// wp-content/plugins/acme-shop/scripts/complete-order.php
$order = wc_get_order(1024);
 
$order->update_status('completed', 'Передан курьеру.');

Метод update_status() меняет состояние, сохраняет заказ и добавляет заметку. Запустите файл через wp eval-file и откройте заказ в «WooCommerce → Заказы»: состояние стало «Выполнен», в блоке «Заметки заказа» появилась запись, покупателю ушло письмо.

Реакция на состояние

Код этого и следующих разделов пишется в includes/orders.php:

// wp-content/plugins/acme-shop/includes/orders.php
add_action('woocommerce_order_status_processing', function (int $orderId, WC_Order $order) {
    $order->add_order_note('Заказ передан в мастерскую.');
}, 10, 2);

Хук срабатывает, когда заказ переходит в состояние «Обработка» — то есть оплачен. Оформите заказ с оплатой при получении: в заметках заказа появится строка «Заказ передан в мастерскую.».

Хуки состояний

// wp-content/plugins/acme-shop/includes/orders.php
add_action('woocommerce_order_status_changed', function (int $orderId, string $from, string $to, WC_Order $order) {
    error_log("Заказ $orderId: $from → $to");
}, 10, 4);

Каждая смена состояния попадёт строкой в журнал wp-content/debug.log, если в wp-config.php включены WP_DEBUG и WP_DEBUG_LOG.

Проверка состояния

if ($order->has_status(['processing', 'completed'])) {
    // заказ оплачен
}
 
if ($order->is_paid()) {
    // то же самое, короче
}

Своё состояние

Мастерской нужно состояние «Изготовлен» между оплатой и отправкой. Его регистрируют двумя фильтрами:

// wp-content/plugins/acme-shop/includes/orders.php
add_filter('woocommerce_register_shop_order_post_statuses', function (array $statuses): array {
    $statuses['wc-ready'] = [
        'label' => 'Изготовлен',
        'public' => false,
        'show_in_admin_all_list' => true,
        'show_in_admin_status_list' => true,
        'label_count' => _n_noop('Изготовлен (%s)', 'Изготовлены (%s)'),
    ];
 
    return $statuses;
});
 
add_filter('wc_order_statuses', function (array $statuses): array {
    $statuses['wc-ready'] = 'Изготовлен';
 
    return $statuses;
});

Первый фильтр сообщает о состоянии системе, второй добавляет его в выпадающий список в редакторе заказа. При регистрации имя пишут с приставкой wc-, а в update_status('ready') и в хуке woocommerce_order_status_ready — без неё.

Частая ошибка

К хуку состояния подключают отправку данных во внешнюю систему и получают дубли: менеджер перевёл заказ в «Обработку», вернул на удержание и снова в «Обработку» — хук сработал дважды. Отмечайте выполненное действие в метаданных заказа и проверяйте отметку перед повтором.