Как использовать WooCommerce order meta для дополнительных данных заказа

Что такое order meta в WooCommerce и зачем использовать дополнительные данные

WooCommerce автоматически сохраняет базовые данные заказа, но часто требуется добавить кастомные поля для хранения специфической информации — например, номер договора, дата установки услуги, или персональные пожелания клиента. Эти данные хранятся в метаданных заказа (order meta) и доступны через API WooCommerce.

Использование order meta позволяет расширить функционал магазина без изменения базы данных и тем, сохраняя совместимость с обновлениями WooCommerce.

Диагностика: как понять, что нужны дополнительные метаданные

Если вы сталкиваетесь с задачами:

• Необходимо сохранять дополнительные данные по заказу, введённые пользователем на странице оформления
• Требуется отображать эти данные в админке и в письмах
• Нужно использовать эти данные для дальнейшей автоматизации (например, передать в CRM или ERP)

— значит, вам нужно работать с order meta.

Пошаговое решение: добавление и вывод кастомных order meta

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

Добавим поле «Номер договора» на страницу оформления заказа, используя хук woocommerce_after_order_notes:

add_action('woocommerce_after_order_notes', 'add_custom_contract_number_field');
function add_custom_contract_number_field( $checkout ) {
    echo '<div id="custom_contract_number_field">';
    woocommerce_form_field( 'contract_number', array(
        'type'          => 'text',
        'class'         => array('contract-number form-row-wide'),
        'label'         => __('Номер договора'),
        'placeholder'   => __('Введите номер договора'),
        'required'      => false,
    ), $checkout->get_value('contract_number') );
    echo '</div>';
}

2. Валидация данных

add_action('woocommerce_checkout_process', 'validate_contract_number_field');
function validate_contract_number_field() {
    if ( isset($_POST['contract_number']) && strlen(trim($_POST['contract_number'])) > 50 ) {
        wc_add_notice(__('Номер договора слишком длинный.'), 'error');
    }
}

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

add_action('woocommerce_checkout_update_order_meta', 'save_contract_number_order_meta');
function save_contract_number_order_meta( $order_id ) {
    if ( ! empty($_POST['contract_number']) ) {
        update_post_meta( $order_id, '_contract_number', sanitize_text_field($_POST['contract_number']) );
    }
}

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

Чтобы видеть номер договора при просмотре заказа в админке:

add_action('woocommerce_admin_order_data_after_billing_address', 'display_contract_number_in_admin_order', 10, 1);
function display_contract_number_in_admin_order( $order ) {
    $contract_number = get_post_meta( $order->get_id(), '_contract_number', true );
    if ( $contract_number ) {
        echo '<p><strong>Номер договора:</strong> ' . esc_html($contract_number) . '</p>';
    }
}

5. Добавление данных в письмо с заказом

add_filter('woocommerce_email_order_meta_keys', 'add_contract_number_to_email_order_meta');
function add_contract_number_to_email_order_meta( $keys ) {
    $keys[] = '_contract_number';
    return $keys;
}

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

• На странице оформления заказа появилось поле «Номер договора»
• При вводе слишком длинного номера должно выводиться сообщение об ошибке
• После оформления заказа в админке в карточке заказа отображается введённый номер договора
• В письмах с информацией о заказе также отображается номер договора

Частые ошибки при работе с order meta и их исправление

• Данные не сохраняются: Проверьте, что woocommerce_checkout_update_order_meta используется правильно и ключ метаданных начинается с подчеркивания (_), чтобы избежать конфликтов.
• Данные не отображаются в админке: Возможно, забыли добавить хук woocommerce_admin_order_data_after_billing_address или используете неправильный ключ.
• Ошибка валидации не показывается: Проверьте, что функция валидации подключена к woocommerce_checkout_process и сообщения добавляются через wc_add_notice.
• Данные не выводятся в письмах: Убедитесь, что фильтр woocommerce_email_order_meta_keys возвращает массив с правильным ключом метаданных.

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

• Всегда используйте sanitize_text_field при сохранении данных, чтобы предотвратить XSS-атаки.
• Не храните слишком большие объемы данных в метаданных заказа, чтобы не нагрузить базу.
• Для сложных данных лучше использовать отдельные таблицы или внешние сервисы.
• Используйте префиксы в именах метаданных, например, _contract_number, чтобы избежать конфликтов с другими плагинами.

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