Как использовать хуки WooCommerce для кастомизации поля оплаты

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

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

Шаг 1. Определяем нужный хук для кастомизации поля оплаты

WooCommerce использует ряд хуков, которые позволяют вмешиваться в процесс оплаты. Основные хуки для кастомизации формы оплаты:

• woocommerce_checkout_fields — фильтр для настройки всех полей оформления заказа;
• woocommerce_after_order_notes — действие для вывода контента после заметок к заказу;
• woocommerce_available_payment_gateways — фильтр для изменения списка доступных платежных шлюзов;
• woocommerce_review_order_before_payment — действие перед блоком оплаты.

Для изменения поля оплаты обычно используется woocommerce_checkout_fields и woocommerce_available_payment_gateways.

Шаг 2. Добавляем/изменяем поле оплаты через woocommerce_checkout_fields

Пример добавления кастомного поля "Номер счета" на страницу оформления заказа:

add_filter('woocommerce_checkout_fields', 'custom_add_account_number_field');
function custom_add_account_number_field($fields) {
    $fields['billing']['billing_account_number'] = array(
        'type'        => 'text',
        'label'       => __('Номер счета', 'woocommerce'),
        'required'    => true,
        'class'       => array('form-row-wide'),
        'clear'       => true,
        'priority'    => 110,
    );
    return $fields;
}

Этот код добавит обязательное текстовое поле в блок данных плательщика.

Шаг 3. Валидируем и сохраняем данные поля оплаты

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

add_action('woocommerce_checkout_process', 'custom_validate_account_number');
function custom_validate_account_number() {
    if (empty($_POST['billing_account_number'])) {
        wc_add_notice(__('Пожалуйста, укажите номер счета.'), 'error');
    }
}

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

Шаг 4. Отображаем поле оплаты в админке и в письмах

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

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

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

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

• Перейдите на страницу оформления заказа, убедитесь, что появилось новое поле "Номер счета" и оно обязательно к заполнению.
• Попытайтесь оформить заказ без заполнения поля — должна появиться ошибка.
• Оформите заказ с заполненным полем, затем проверьте в админке WooCommerce в деталях заказа наличие номера счета.
• Проверьте уведомления по электронной почте — в письме должен присутствовать номер счета.

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

• Поле не отображается на форме: проверьте, что фильтр woocommerce_checkout_fields подключен корректно и функция возвращает массив полей.
• Ошибка при валидации не появляется: убедитесь, что в форме поле имеет имя billing_account_number и совпадает с проверкой в $_POST.
• Данные не сохраняются: проверьте, что используете хук woocommerce_checkout_update_order_meta и сохраняете мета-данные с уникальным ключом.
• Данные не отображаются в письмах: убедитесь, что используете фильтр woocommerce_email_order_meta_fields и возвращаете корректный массив.

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

• Используйте sanitize_text_field() при сохранении пользовательских данных, чтобы избежать XSS-уязвимостей.
• Не выводите пользовательские данные без экранирования — применяйте esc_html() или аналогичные функции.
• Не загружайте лишние плагины для простой кастомизации полей — хуки WooCommerce достаточно мощны и гибки.
• Используйте приоритеты в хуках, чтобы избежать конфликтов с другими плагинами или темами, особенно если поле не отображается.

Сравнение вариантов кастомизации поля оплаты в WooCommerce