Что такое хук woocommerce_email_attachments и где он применяется
Хук woocommerce_email_attachments позволяет добавить вложения к email-уведомлениям WooCommerce. Он вызывается при формировании письма и даёт возможность расширить стандартный набор вложений — например, прикрепить PDF-счёт, инструкции или сертификаты.
Используется во всех email-уведомлениях WooCommerce, включая уведомления о заказах, возвратах, смене статуса и др.
Диагностика проблемы: вложения не добавляются к письмам WooCommerce
Если вы добавляли вложения через хук, но в письмах их нет, проверьте:
- Правильность пути к файлам — должен быть полный абсолютный путь на сервере.
- Работоспособность функции, подключенной к хуку (нет PHP-ошибок).
- Подключение хука происходит в нужное время — обычно в
functions.phpтемы или в плагине. - Формат возвращаемого массива вложений — это должен быть массив путей к файлам.
- Совместимость с другими плагинами, которые могут влиять на отправку писем.
Пошаговое решение: добавление PDF-файла к письму о новом заказе
Рассмотрим пример, когда нужно автоматически прикрепить PDF-счёт к письму покупателю после оформления заказа.
1. Создаём функцию для добавления вложения
add_filter('woocommerce_email_attachments', 'add_pdf_invoice_to_email', 10, 3);
function add_pdf_invoice_to_email($attachments, $email_id, $order) {
// Целевой email — новое оформление заказа покупателем
if ($email_id === 'customer_processing_order' && is_a($order, 'WC_Order')) {
$upload_dir = wp_upload_dir();
$pdf_path = $upload_dir['basedir'] . '/invoices/invoice-' . $order->get_id() . '.pdf';
if (file_exists($pdf_path)) {
$attachments[] = $pdf_path;
}
}
return $attachments;
}
Обратите внимание:
$email_id === 'customer_processing_order'— проверяем, что письмо именно о новом заказе.- Путь к PDF формируется на основе ID заказа и папки
wp-content/uploads/invoices/. - Файл добавляется только если существует.
2. Генерация PDF-файла
Для автоматической генерации PDF-счёта используйте сторонние библиотеки (например, TCPDF) или плагины (WooCommerce PDF Invoices). Здесь важно, чтобы файл был создан до отправки письма.
Проверка результата
Чтобы убедиться, что вложение добавлено:
- Оформите тестовый заказ с тестовой почтой.
- Проверьте письмо в почтовом клиенте — должен быть вложен PDF-файл.
- Если письмо не содержит вложения, включите логирование ошибок PHP и проверьте путь к файлу.
Частые ошибки и как их исправить
- Неправильный путь к файлу: используйте
wp_upload_dir()или абсолютные пути, относительные пути не работают. - Файл не существует на момент отправки письма: убедитесь, что PDF генерируется заранее, либо отложите отправку.
- Функция не подключена или подключена в неправильном месте: добавляйте хук в
functions.phpактивной темы или в собственный плагин. - Конфликты с другими плагинами: временно деактивируйте плагины, которые могут вмешиваться в отправку почты.
Практические советы по безопасности и производительности
- Проверяйте права доступа к директории с вложениями — они должны быть доступны серверу, но не открыты для публичного просмотра.
- Генерируйте PDF-файлы по событию, а не на лету при отправке почты, чтобы не задерживать отправку.
- Используйте кеширование, чтобы не создавать один и тот же PDF несколько раз.
- Ограничивайте добавляемые вложения по размеру, чтобы не перегружать почтовые сервера.
Сравнение способов добавления вложений к письмам WooCommerce
| Метод | Описание | Преимущества | Минусы |
|---|---|---|---|
Хук woocommerce_email_attachments | Добавление вложений через фильтр PHP | Полный контроль, гибкость, можно добавлять любые файлы | Необходима генерация файлов заранее, требует навыков разработки |
| Плагины PDF Invoices | Автоматическая генерация и добавление счетов | Простота установки, готовые шаблоны, поддержка обновлений | Меньше гибкости, возможны конфликты с кастомным кодом |
| Встроенные возможности SMTP-сервера | Добавление вложений через почтовый сервер (редко) | Не требует изменений кода | Ограничено функционалом SMTP, мало распространено |