WooCommerce: как использовать хуки для изменения статей оплаты

Диагностика проблемы: необходимость кастомизации статей оплаты в WooCommerce

В стандартной установке WooCommerce статья оплаты (payment method description) выводится без возможности удобного изменения через админку или настройки. Многие разработчики и владельцы магазинов сталкиваются с задачей добавить дополнительную информацию к способам оплаты — например, инструкции, условия или контактные данные.

При попытках изменить описание напрямую в PHP-файлах плагина или шаблона возможны проблемы с обновлениями и потерей изменений. Поэтому правильное решение — использовать хуки WooCommerce для изменения вывода без риска сломать обновления.

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

1. Определяем фильтр для изменения описания способа оплаты

WooCommerce использует фильтр woocommerce_gateway_description для вывода текста описания способа оплаты. Он принимает два параметра: описание и объект платежного шлюза.

2. Добавляем свой фильтр в файл functions.php вашей темы или в плагин

add_filter('woocommerce_gateway_description', 'custom_payment_gateway_description', 20, 2);
function custom_payment_gateway_description($description, $payment_gateway) {
    // Пример: добавить дополнительный текст для способа оплаты 'cod' (наложенный платеж)
    if ($payment_gateway->id === 'cod') {
        $custom_text = '<p><strong>Внимание:</strong> Оплата наличными при получении. Пожалуйста, подготовьте сумму заранее.</p>';
        return $description . $custom_text;
    }
    return $description;
}

3. Кастомизация для нескольких способов оплаты

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

add_filter('woocommerce_gateway_description', 'custom_payment_gateway_description_multi', 20, 2);
function custom_payment_gateway_description_multi($description, $payment_gateway) {
    $texts = [
        'cod' => '<p><strong>Наложенный платеж:</strong> Готовьте сумму при доставке.</p>',
        'bacs' => '<p><strong>Банковский перевод:</strong> Средства зачисляются в течение 1-3 рабочих дней.</p>',
    ];
    if (array_key_exists($payment_gateway->id, $texts)) {
        return $description . $texts[$payment_gateway->id];
    }
    return $description;
}

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

Чтобы убедиться, что описание изменилось:

• Откройте страницу оформления заказа (checkout).
• Выберите способ оплаты, для которого вы добавили описание (например, «Наложенный платеж»).
• Убедитесь, что под названием способа оплаты отображается ваш дополнительный текст.

Если описание не изменилось, проверьте активность фильтра и наличие ошибок в коде.

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

• Описание не меняется: возможно, фильтр добавлен с неправильным приоритетом или не подключен. Проверьте, что код находится в functions.php активной темы или в плагине и что приоритет 20 достаточно высокий.
• HTML не отображается корректно: WooCommerce по умолчанию экранирует некоторые специальные символы. Если описание выводится как текст с тегами, попробуйте использовать хук woocommerce_gateway_description вместе с функцией wp_kses_post для разрешения безопасного HTML.
• Конфликт с другими плагинами: некоторые плагины оплаты могут переопределять описание. В таком случае проверяйте документацию конкретного плагина или используйте более специфичные хуки.

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

• Используйте функцию wp_kses_post() для безопасного вывода HTML в описании, чтобы избежать XSS-уязвимостей.
• Не добавляйте тяжелый или динамический контент в описание, чтобы не замедлять загрузку страницы оформления заказа.
• Тестируйте изменения на копии сайта или в staging-среде, чтобы избежать сбоев в работе магазина.

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