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

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

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

Что делает хук woocommerce_checkout_update_order_meta

Этот хук вызывается после успешного создания объекта заказа, но до завершения оформления, позволяя безопасно добавлять или изменять метаданные.
Использовать его можно так:

add_action('woocommerce_checkout_update_order_meta', 'custom_save_order_meta', 10, 2);
function custom_save_order_meta($order_id, $data) {
    // ваш код
}

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

1. Определение данных для сохранения

Для примера сохраним дополнительное поле из формы оформления — "Номер клиента" (client_number), добавленное в кастомное поле формы.

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

Добавляем поле в форму через хук woocommerce_after_order_notes:

add_action('woocommerce_after_order_notes', 'add_custom_checkout_field');
function add_custom_checkout_field($checkout) {
    woocommerce_form_field('client_number', array(
        'type'          => 'text',
        'class'         => array('client-number-field form-row-wide'),
        'label'         => __('Номер клиента'),
        'placeholder'   => __('Введите номер клиента'),
        'required'      => false,
    ), $checkout->get_value('client_number'));
}

3. Валидация поля при отправке

Добавляем простой валидатор (опционально):

add_action('woocommerce_checkout_process', 'validate_client_number_field');
function validate_client_number_field() {
    if ( ! empty($_POST['client_number']) && ! preg_match('/^\d+$/', $_POST['client_number']) ) {
        wc_add_notice(__('Номер клиента должен содержать только цифры.'), 'error');
    }
}

4. Сохранение метаданных в заказ

Основной шаг — используем хук woocommerce_checkout_update_order_meta для сохранения:

add_action('woocommerce_checkout_update_order_meta', 'save_client_number_to_order_meta', 10, 2);
function save_client_number_to_order_meta($order_id, $data) {
    if ( ! empty($_POST['client_number']) ) {
        update_post_meta($order_id, '_client_number', sanitize_text_field($_POST['client_number']));
    }
}

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

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

• В админке WooCommerce откройте заказ, нажмите "Редактировать" и проверьте наличие метаполя (через расширения или плагины для отображения метаданных).
• Добавьте в functions.php временный вывод для отладки:

add_action('woocommerce_admin_order_data_after_order_details', 'display_client_number_in_admin_order');
function display_client_number_in_admin_order($order) {
    $client_number = get_post_meta($order->get_id(), '_client_number', true);
    if ($client_number) {
        echo '<p><strong>Номер клиента:</strong> ' . esc_html($client_number) . '</p>';
    }
}

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

• Метаданные не сохраняются: проверьте, что ключ $_POST совпадает с именем поля формы.
• Данные не отображаются в заказе: убедитесь, что используете правильный ключ метаполя (обычно с префиксом _).
• Валидация не срабатывает: проверьте, что функция валидации подключена к хуку woocommerce_checkout_process.
• Безопасность: всегда используйте sanitize_text_field() или другие функции очистки данных перед сохранением.

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

• Используйте nonce-поля для защиты пользовательских форм от CSRF, если добавляете сложные поля.
• Избегайте тяжелых операций при сохранении метаданных, чтобы не замедлять оформление заказа.
• Регулярно проверяйте, что метаданные не содержат вредоносных данных через функции очистки.

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