Как использовать хук WooCommerce Email Attachments для добавления вложений в письма

Что делает хук woocommerce_email_attachments и зачем он нужен

Хук woocommerce_email_attachments позволяет добавить дополнительные файлы в любые email-уведомления WooCommerce, отправляемые сайтом. Это часто требуется, например, для отправки PDF-счетов, инструкций, сертификатов или других документов вместе с письмом.

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

Диагностика: как понять, что вложения не добавляются

• В письмах отсутствуют ожидаемые вложения.
• Файлы не загружаются или путь к вложению неверен.
• Письмо отправляется, но без прикрепленных файлов.
• Ошибки в логах PHP или WooCommerce, связанные с функцией добавления вложений.

Для диагностики можно включить режим отладки WooCommerce и PHP, проверить логи, а также протестировать код на локальной среде.

Пошаговое решение: добавление вложения в email WooCommerce

1. Определите, в какие письма нужно добавить вложение

Параметр $email_id в фильтре позволяет отфильтровать нужные письма. Например, customer_completed_order — письмо о выполненном заказе.

2. Подготовьте путь к файлу вложения

Важно, чтобы файл был доступен на сервере и корректно указывался абсолютным путём или URL.

3. Добавьте код в файл functions.php или кастомный плагин

add_filter('woocommerce_email_attachments', 'add_attachment_to_woocommerce_email', 10, 3);
function add_attachment_to_woocommerce_email($attachments, $email_id, $order) {
    // Добавляем вложение только для письма о выполненном заказе
    if ($email_id === 'customer_completed_order' && is_a($order, 'WC_Order')) {
        $upload_dir = wp_upload_dir();
        $file_path = $upload_dir['basedir'] . '/invoices/invoice-' . $order->get_id() . '.pdf';
        if (file_exists($file_path)) {
            $attachments[] = $file_path;
        }
    }
    return $attachments;
}

В этом примере мы прикрепляем PDF-счёт, который должен находиться в папке wp-content/uploads/invoices/ с именем, соответствующим номеру заказа.

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

1. Создайте тестовый заказ и переведите его в статус "завершён".
2. Проверьте письмо, которое получает клиент — должно содержать вложение PDF.
3. Если письмо не приходит, включите логирование WooCommerce и проверьте ошибки.
4. Для тестирования можно использовать плагин WP Mail Logging или аналогичный.

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

• Неправильный путь к файлу: Используйте wp_upload_dir() для построения абсолютного пути, избегайте относительных путей.
• Файл отсутствует: Проверьте существование файла с помощью file_exists() перед добавлением.
• Письмо не отправляется: Проверьте, что $order передаётся корректно и что $email_id совпадает с нужным.
• Проблемы с правами доступа: Убедитесь, что веб-сервер имеет права на чтение файлов вложений.

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

• Не прикрепляйте слишком большие файлы — это может замедлить отправку и повлиять на доставляемость.
• Генерируйте вложения заранее (например, при создании заказа), чтобы не создавать их во время отправки письма.
• Храните вложения в защищённых папках с правильными правами доступа.
• Ограничьте добавление вложений только к нужным письмам, чтобы избежать ненужной нагрузки.

Сравнение способов добавления вложений в письма WooCommerce

Способ	Плюсы	Минусы	Пример использования
Использование woocommerce_email_attachments	Гибко, без плагинов, работает со всеми письмами	Требует навыков PHP, управление файлами на сервере	Пример в статье
Плагины для счетов и вложений (например, WooCommerce PDF Invoices)	Простота использования, готовый функционал	Меньшая гибкость, возможные конфликты	Автоматическая генерация счетов и вложений
Модификация шаблонов email	Можно вставлять вложения и контент	Сложно поддерживать при обновлениях WooCommerce	Требует кастомной темы или дочерней темы