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

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

WooCommerce отправляет клиентам и админам набор стандартных писем (подтверждение заказа, уведомление о доставке, возврате и т.д.). Часто требуется подстроить содержимое этих писем под бизнес-задачи — добавить дополнительную информацию, изменить текст, вставить ссылки или кастомный блок. Прямое редактирование шаблонов в папке woocommerce/templates/emails неудобно и рискованно: при обновлении плагина изменения потеряются. Правильный способ — использовать хуки (actions и filters), которые предоставляет WooCommerce для писем.

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

WooCommerce использует достаточно много хуков в шаблонах писем, но ключевые из них:

• woocommerce_email_header — выводит заголовок письма;
• woocommerce_email_footer — выводит футер;
• woocommerce_email_order_details — выводит детали заказа;
• woocommerce_email_before_order_table — перед таблицей заказа;
• woocommerce_email_after_order_table — после таблицы заказа;
• woocommerce_email_customer_details — детали покупателя;
• woocommerce_email_order_meta — метаданные заказа;
• Фильтр woocommerce_email_subject_{$email_id} для изменения темы письма;
• Фильтр woocommerce_email_recipient_{$email_id} для изменения получателя.

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

Допустим, нужно добавить в письмо с подтверждением заказа дополнительную благодарность и ссылку на страницу поддержки.

1. Создайте плагин или добавьте код в functions.php активной темы (желательно дочерней).

2. Используйте хук woocommerce_email_after_order_table и проверяйте тип письма, чтобы вставлять блок только в нужные письма.

add_action('woocommerce_email_after_order_table', 'wpmanual_add_custom_text_to_email', 10, 4);
function wpmanual_add_custom_text_to_email($order, $sent_to_admin, $plain_text, $email) {
    // Проверяем, что письмо — новое подтверждение заказа для клиента
    if ($email->id === 'customer_processing_order' && !$sent_to_admin) {
        echo '<div style="padding:10px; background:#f5f5f5; margin-top:20px; border-radius:4px;">';
        echo '<p>Спасибо за ваш заказ! Если возникнут вопросы, пожалуйста, посетите нашу <a href="' . esc_url(site_url('/support')) . '">страницу поддержки</a>.</p>';
        echo '</div>';
    }
}

3. Сохраните изменения.

Как проверить, что решение сработало

• Создайте тестовый заказ в WooCommerce с адресом электронной почты, к которому у вас есть доступ.
• Убедитесь, что письмо "Обработка заказа" (customer_processing_order) отправлено и содержит ваш кастомный блок с текстом и ссылкой.
• Проверьте отображение в HTML-версии письма и, при необходимости, в plain-text.

Частые ошибки при кастомизации писем через хуки и как их исправить

• Кастомный блок не отображается: проверьте правильность ID письма в условии ($email->id), он должен совпадать с нужным типом письма. Используйте error_log(print_r($email->id, true)) для отладки.
• Изменения пропадают после обновления WooCommerce: не редактируйте файлы плагина напрямую, используйте хуки в functions.php или собственном плагине.
• Код ломает HTML письма: убедитесь, что в коде нет неэкранированных символов, используйте esc_url() и esc_html() для вывода.
• Письмо не доходит до получателя: проверьте настройки SMTP и логи отправки, возможно, проблема вне кода.

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

• Не вставляйте в письма потенциально уязвимый пользовательский ввод без фильтрации и экранирования.
• Не делайте тяжелых запросов к базе данных или API в хуках писем — это может замедлить отправку.
• Для сложных изменений лучше создавать собственные шаблоны писем и подключать их через фильтр woocommerce_locate_template.
• Используйте кэширование данных, которые не меняются между письмами, чтобы снизить нагрузку.

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