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

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

Иногда требуется собрать дополнительную информацию от клиента при оформлении заказа, например, номер паспорта, дату рождения или комментарии к доставке. WooCommerce поддерживает добавление пользовательских полей (custom fields), но для корректной работы нужно правильно использовать хуки, чтобы данные сохранялись, отображались и передавались в админку и клиенту.

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

Основные хуки для добавления кастомных полей в форму оформления заказа (checkout) и сохранения их в мета-данных заказа:

• woocommerce_after_order_notes — вывод поля в форме оформления заказа;
• woocommerce_checkout_update_order_meta — сохранение данных в метаданные заказа;
• woocommerce_admin_order_data_after_billing_address — вывод данных в админке у заказа;
• woocommerce_email_order_meta_fields — добавление полей в письма клиенту.

Пример: добавляем текстовое поле «Номер паспорта»

add_action('woocommerce_after_order_notes', 'add_passport_number_field');
function add_passport_number_field( $checkout ) {
    echo '<div id="passport_number_field">';
    woocommerce_form_field( 'passport_number', array(
        'type'          => 'text',
        'class'         => array('passport-number form-row-wide'),
        'label'         => __('Номер паспорта'),
        'placeholder'   => __('Введите номер паспорта'),
        'required'      => true,
    ), $checkout->get_value( 'passport_number' ));
    echo '</div>';
}

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

add_action('woocommerce_admin_order_data_after_billing_address', 'display_passport_number_admin_order', 10, 1);
function display_passport_number_admin_order($order){
    $passport = get_post_meta($order->get_id(), 'passport_number', true);
    if($passport) {
        echo '<p><strong>Номер паспорта:</strong> ' . esc_html($passport) . '</p>';
    }
}

add_filter('woocommerce_email_order_meta_fields', 'add_passport_number_to_emails', 10, 3);
function add_passport_number_to_emails( $fields, $sent_to_admin, $order ) {
    $passport = get_post_meta($order->get_id(), 'passport_number', true);
    if ( $passport ) {
        $fields['passport_number'] = array(
            'label' => __('Номер паспорта'),
            'value' => $passport,
        );
    }
    return $fields;
}

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

1. Перейдите в оформление заказа, убедитесь, что поле «Номер паспорта» отображается и является обязательным.
2. Оформите заказ, заполнив это поле.
3. В админке WooCommerce откройте заказ и убедитесь, что введённое значение отображается в разделе с данными покупателя.
4. Проверьте письмо с подтверждением заказа — в нем должно содержаться поле «Номер паспорта».

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

• Поле не сохраняется: часто из-за отсутствия обработки в woocommerce_checkout_update_order_meta или неправильной проверки $_POST.
• Поле не отображается в админке: забыли подключить хук woocommerce_admin_order_data_after_billing_address или неправильно получили ID заказа.
• Поля не показываются в письмах: не добавили фильтр woocommerce_email_order_meta_fields или вернули неправильный формат массива.
• Невалидный ввод: не использовали функции sanitize_text_field и не добавили атрибут required для обязательных полей.

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

• Обязательно очищайте и валидируйте пользовательский ввод с помощью стандартных функций WordPress (sanitize_text_field, esc_html).
• Не храните чувствительные данные в открытом виде — если требуется, подумайте о шифровании.
• Добавляйте минимально необходимые поля, чтобы не увеличивать нагрузку на базу и не усложнять UX.
• Для массовых изменений используйте WP CLI или оптимизированные запросы, если нужно обновлять мета-данные в большом количестве заказов.

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

Метод	Плюсы	Минусы
Через хуки и функции в functions.php	Полный контроль, бесплатно, гибкость	Требует навыков программирования, ошибки влияют на сайт
Плагины для пользовательских полей (например, Checkout Field Editor)	Простота, визуальный интерфейс, быстрая настройка	Дополнительный плагин — нагрузка, ограничения по кастомизации
Использование сторонних CRM и интеграций	Автоматизация, расширенные возможности	Сложность настройки, возможны задержки передачи данных