Как использовать хук woocommerce_checkout_update_order_meta для добавления данных к заказу

Что такое хук woocommerce_checkout_update_order_meta и зачем он нужен

Хук woocommerce_checkout_update_order_meta вызывается при оформлении заказа в WooCommerce после того, как пользователь отправил форму на странице оформления, но перед сохранением данных заказа. Это идеальное место для добавления или изменения метаданных заказа на основе данных из формы или другой логики.

На практике этот хук часто используется для сохранения дополнительных полей, добавленных к форме оформления заказа, или для передачи кастомных данных в заказ.

Диагностика задачи: как понять, что нужно использовать этот хук

Если вы добавляете кастомные поля на страницу оформления заказа — например, поле с номером налоговой или дополнительными инструкциями — и эти данные не сохраняются в заказе, значит, нужно использовать woocommerce_checkout_update_order_meta для сохранения этих данных в базе.

Пример типичной проблемы: добавили поле custom_note в checkout, но после оформления заказа значение не сохраняется и не отображается в панели администратора.

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

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-class form-row-wide'),
        'label'         => __('Дополнительная заметка'),
        'placeholder'   => __('Введите заметку'),
        'required'      => false,
    ), $checkout->get_value( 'custom_note' ));
}

2. Проверяем поле при отправке формы (если нужно)

add_action('woocommerce_checkout_process', 'validate_custom_note_field');
function validate_custom_note_field() {
    if ( ! $_POST['custom_note'] ) {
        // Если поле обязательное, можно добавить ошибку
        // wc_add_notice( __('Пожалуйста, заполните дополнительную заметку.'), 'error' );
    }
}

3. Сохраняем данные поля в метаданные заказа

add_action( 'woocommerce_checkout_update_order_meta', 'save_custom_note_order_meta' );
function save_custom_note_order_meta( $order_id ) {
    if ( ! empty( $_POST['custom_note'] ) ) {
        update_post_meta( $order_id, '_custom_note', sanitize_text_field( $_POST['custom_note'] ) );
    }
}

4. Отображаем сохранённые данные в админке заказа

add_action( 'woocommerce_admin_order_data_after_billing_address', 'display_custom_note_admin_order', 10, 1 );
function display_custom_note_admin_order( $order ){
    $custom_note = get_post_meta( $order->get_id(), '_custom_note', true );
    if ( $custom_note ) {
        echo '<p><strong>Дополнительная заметка:</strong> ' . esc_html( $custom_note ) . '</p>';
    }
}

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

• Откройте страницу оформления заказа, проверьте, что поле Дополнительная заметка отображается.
• Заполните поле, отправьте заказ.
• В админке WooCommerce откройте заказ и убедитесь, что дополнительная заметка отображается под адресом оплаты.
• Проверьте, что значение сохраняется в базе данных в таблице wp_postmeta с ключом _custom_note.

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

• Поле не сохраняется: проверьте, что имя поля в $_POST совпадает с тем, что указано в woocommerce_form_field и в функции сохранения.
• Данные не отображаются в админке: убедитесь, что используете правильный хук для вывода и что обращаетесь к метаданным по правильному ключу.
• Ошибка при валидации: если поле обязательное, используйте хук woocommerce_checkout_process для проверки и вывода ошибок через wc_add_notice.
• Безопасность: всегда фильтруйте данные с помощью sanitize_text_field или других функций очистки перед сохранением.

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

• Минимизируйте использование глобальных переменных $_POST, проверяйте существование ключей через isset().
• Сохраняйте только нужные данные, избегайте избыточных метаданных, чтобы не раздувать базу данных.
• Используйте nonce-поля и проверку прав пользователя, если добавляете поля в другие части административной панели.

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