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

Что такое WooCommerce Order Meta и зачем он нужен

WooCommerce Order Meta — это механизм хранения дополнительных данных заказа, которые не входят в стандартный набор информации. Часто возникает необходимость добавить уникальные данные, например, инструкции по доставке, индивидуальные параметры товара или внутренние заметки. Использование order meta позволяет сохранять эти данные в базе и отображать их в админке, письмах и на странице заказа.

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

Если в вашем проекте:

• нужно сохранить дополнительную информацию с форм заказа;
• вы хотите добавить пользовательские поля к заказу;
• необходимо передавать специфичные данные в сторонние сервисы через хуки;
• нужно отобразить дополнительные данные в админке WooCommerce или на странице пользователя;

— тогда order meta это правильное решение.

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

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

Добавим поле "Инструкции для доставки" на страницу оформления заказа:

add_action('woocommerce_after_order_notes', 'add_delivery_instructions_checkout_field');
function add_delivery_instructions_checkout_field( $checkout ) {
    woocommerce_form_field( 'delivery_instructions', array(
        'type'          => 'textarea',
        'class'         => array('form-row-wide'),
        'label'         => __('Инструкции для доставки'),
        'placeholder'   => __('Укажите дополнительные пожелания к доставке'),
        'required'      => false,
    ), $checkout->get_value('delivery_instructions') );
}

2. Сохранение данных в order meta после оформления заказа

add_action('woocommerce_checkout_update_order_meta', 'save_delivery_instructions_order_meta');
function save_delivery_instructions_order_meta( $order_id ) {
    if ( ! empty( $_POST['delivery_instructions'] ) ) {
        update_post_meta( $order_id, '_delivery_instructions', sanitize_textarea_field( $_POST['delivery_instructions'] ) );
    }
}

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

add_action('woocommerce_admin_order_data_after_order_details', 'display_delivery_instructions_admin_order');
function display_delivery_instructions_admin_order( $order ){
    $instructions = get_post_meta( $order->get_id(), '_delivery_instructions', true );
    if ( $instructions ) {
        echo '<p><strong>Инструкции для доставки:</strong> ' . esc_html( $instructions ) . '</p>';
    }
}

4. Вывод данных на странице "Спасибо за заказ" и в письме

Для страницы благодарности:

add_action('woocommerce_thankyou', 'display_delivery_instructions_thankyou', 20);
function display_delivery_instructions_thankyou( $order_id ) {
    $instructions = get_post_meta( $order_id, '_delivery_instructions', true );
    if ( $instructions ) {
        echo '<h2>Ваши инструкции по доставке</h2><p>' . esc_html( $instructions ) . '</p>';
    }
}

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

add_action('woocommerce_email_customer_details', 'add_delivery_instructions_to_email', 20, 3);
function add_delivery_instructions_to_email( $order, $sent_to_admin, $plain_text ) {
    $instructions = get_post_meta( $order->get_id(), '_delivery_instructions', true );
    if ( $instructions ) {
        if ( $plain_text ) {
            echo "Инструкции для доставки: " . $instructions . "\n";
        } else {
            echo '<h3>Инструкции для доставки</h3><p>' . esc_html( $instructions ) . '</p>';
        }
    }
}

Как проверить, что данные order meta сохранились и отображаются

• После оформления тестового заказа проверьте, что поле "Инструкции для доставки" заполнено.
• В админке WooCommerce откройте заказ и убедитесь, что данные отображаются под деталями заказа.
• На странице "Спасибо за заказ" проверьте отображение введённой информации.
• Получите письмо с подтверждением заказа и проверьте наличие инструкции в тексте.
• Если не видите данных, проверьте наличие ошибок в логах и правильность кода.

Частые ошибки при работе с WooCommerce Order Meta и их исправление

• Данные не сохраняются: проверьте, что имя поля в форме совпадает с ключом в $_POST и что хук woocommerce_checkout_update_order_meta используется корректно.
• Данные не отображаются в админке: убедитесь, что используете правильный хук woocommerce_admin_order_data_after_order_details и что meta key соответствует сохранённому.
• Проблемы с безопасностью: применяйте функции очистки данных, например sanitize_textarea_field(), чтобы избежать XSS.
• Данные не выводятся в письмах: проверьте, что хук woocommerce_email_customer_details вызывается с правильными параметрами и что добавленный контент корректно обрабатывается для plain text и HTML форматов.

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

• Всегда очищайте и валидируйте пользовательские данные перед сохранением в meta.
• Используйте префиксы для ключей meta, чтобы избежать конфликтов, например _delivery_instructions.
• Не храните избыточные или большие объёмы данных в order meta — данные влияют на размер базы и скорость запросов.
• Для вывода данных используйте кеширование, если планируется частый запрос одних и тех же meta.
• Регулярно проверяйте совместимость кода с обновлениями WooCommerce и WordPress.

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