Добавление собственных полей в заказ WooCommerce через хук woocommerce_checkout_update_order_meta

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

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

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

Для начала нужно вывести дополнительное поле в форме оформления. Это делается через фильтр woocommerce_checkout_fields. Например, добавим текстовое поле "Номер договора":

add_filter('woocommerce_checkout_fields', 'wpboard_add_custom_checkout_field');
function wpboard_add_custom_checkout_field($fields) {
    $fields['billing']['billing_contract_number'] = array(
        'type'        => 'text',
        'label'       => 'Номер договора',
        'placeholder' => 'Введите номер договора',
        'required'    => false,
        'class'       => array('form-row-wide'),
        'priority'    => 120,
    );
    return $fields;
}

Сохраняем данные собственного поля в заказ через хук woocommerce_checkout_update_order_meta

Чтобы сохранить введённое значение в метаданные заказа, используем хук woocommerce_checkout_update_order_meta. В обработчике проверяем наличие поля и сохраняем его:

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

Отображение собственного поля в админке WooCommerce и в письмах

Чтобы видеть введённые данные в админке заказа, добавим вывод метаполя на страницу редактирования заказа с помощью хука woocommerce_admin_order_data_after_billing_address:

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

Чтобы добавить поле в письма, используйте фильтр woocommerce_email_order_meta_fields:

add_filter('woocommerce_email_order_meta_fields', 'wpboard_add_custom_field_to_emails', 10, 3);
function wpboard_add_custom_field_to_emails($fields, $sent_to_admin, $order) {
    $contract_number = get_post_meta($order->get_id(), '_billing_contract_number', true);
    if ($contract_number) {
        $fields['billing_contract_number'] = array(
            'label' => 'Номер договора',
            'value' => $contract_number,
        );
    }
    return $fields;
}

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

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

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

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

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

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

Краткий чек-лист для добавления собственного поля в оформление заказа WooCommerce

1. Добавить поле через фильтр woocommerce_checkout_fields.
2. Сохранить данные через хук woocommerce_checkout_update_order_meta.
3. Отобразить поле в админке с помощью woocommerce_admin_order_data_after_billing_address.
4. Добавить в письма через фильтр woocommerce_email_order_meta_fields.
5. Проверить корректность отображения и сохранения данных.
6. Добавить валидацию при необходимости через woocommerce_checkout_process.