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

Диагностика задачи: зачем менять метаданные заказа в WooCommerce

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

Основные хуки для работы с метаданными заказа на этапе оформления

В WooCommerce есть несколько хуков, которые срабатывают на разных этапах оформления заказа. Для изменения метаданных заказа до его сохранения чаще всего применяются:

• woocommerce_checkout_create_order — срабатывает сразу после создания объекта WC_Order, до сохранения в базу.
• woocommerce_checkout_update_order_meta — срабатывает после сохранения основного заказа, позволяет записать дополнительные метаданные.
• woocommerce_checkout_order_processed — запускается после создания и обработки заказа.

Когда использовать какой хук

• woocommerce_checkout_create_order: если нужно изменить свойства объекта заказа или добавить метаданные программно перед сохранением.
• woocommerce_checkout_update_order_meta: если нужно добавить или обновить метаданные после сохранения заказа.
• woocommerce_checkout_order_processed: для триггеров задач, связанных с уже созданным заказом (email, интеграции).

Пошаговое решение: добавляем и изменяем метаданные заказа через хук

Пример: добавим новое кастомное поле custom_note, которое пользователь вводит на странице оформления и запишем его в метаданные заказа.

1. Добавление поля на страницу оформления заказа

add_action('woocommerce_after_order_notes', 'add_custom_checkout_field');
function add_custom_checkout_field($checkout) {
    woocommerce_form_field('custom_note', array(
        'type'        => 'text',
        'class'       => array('custom-note form-row-wide'),
        'label'       => __('Дополнительная заметка'),
        'placeholder' => __('Введите заметку'),
        'required'    => false,
    ), $checkout->get_value('custom_note'));
}

2. Валидация поля (если нужно)

add_action('woocommerce_checkout_process', 'validate_custom_checkout_field');
function validate_custom_checkout_field() {
    if (!empty($_POST['custom_note']) && strlen(trim($_POST['custom_note'])) > 200) {
        wc_add_notice(__('Заметка слишком длинная (максимум 200 символов).'), 'error');
    }
}

3. Сохранение метаданных заказа с помощью woocommerce_checkout_create_order

add_action('woocommerce_checkout_create_order', 'save_custom_note_to_order', 20, 2);
function save_custom_note_to_order($order, $data) {
    if (!empty($_POST['custom_note'])) {
        $order->update_meta_data('custom_note', sanitize_text_field($_POST['custom_note']));
    }
}

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

Чтобы убедиться, что метаданные сохранены правильно:

• Оформите тестовый заказ, заполнив поле "Дополнительная заметка".
• В административной панели WordPress откройте заказ (WooCommerce → Заказы).
• Проверьте наличие метаданных: в разделе Дополнительные поля заказа должна отображаться ваша заметка.
• При необходимости выведите метаданные в шаблоне письма или на странице заказа с помощью $order->get_meta('custom_note').

Частые ошибки при работе с метаданными заказа и их исправление

• Метаданные не сохраняются: вероятно, используется неправильный хук или отсутствует вызов update_meta_data на объекте заказа. Используйте woocommerce_checkout_create_order и метод update_meta_data, а не update_post_meta.
• Данные сохраняются, но не отображаются: убедитесь, что метаданные выводятся корректно с помощью $order->get_meta('ключ'). В шаблоне письма или на странице заказа выведите это значение.
• Проблемы с безопасностью: не забывайте фильтровать входящие данные через sanitize_text_field или другие функции очистки.
• Поле не отображается на форме: проверьте правильность хука добавления поля и отсутствие конфликтов с другими плагинами.

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

• Для кастомных данных используйте отдельные ключи метаданных с префиксом, например, custom_, чтобы избежать конфликтов.
• Не сохраняйте большие массивы данных в метаданные заказа — это может замедлить загрузку страницы заказа.
• Добавляйте минимальную валидацию пользовательских данных, чтобы не допустить ошибочных или вредоносных значений.
• Для массовых изменений метаданных используйте WP CLI или отдельные скрипты вне фронтенда, чтобы не нагружать сайт.

Сравнение вариантов добавления метаданных заказа