理解WooCommerce邮件系统与附件机制
WooCommerce通过其内置的邮件系统处理所有订单相关的通知。当我们需要发送自定义邮件或在现有邮件中添加特定内容时，通常会通过WordPress的动作钩子（Action Hooks）来介入。在邮件中添加附件是常见需求，例如发送礼品PDF、发票或其他文档。
实现附件发送的关键在于正确使用WooCommerce的邮件发送器实例 (WC()->mailer()) 及其 send() 方法。此方法不仅负责邮件内容的构建和发送，也支持附件的集成。
常见问题与解决方案
在尝试为WooCommerce自定义邮件添加附件时，开发者常遇到以下问题：
- 使用过时的全局变量或方法： 早期版本的WooCommerce可能推荐使用 global $woocommerce; $woocommerce->mailer();。然而，当前推荐且更简洁的方式是使用 WC()->mailer()，这能确保您获取到最新的邮件发送器实例。
- 附件路径不正确： 直接硬编码URL路径（如 yoursite.com/wp-content/file.pdf）是不可靠的，因为这并非文件系统路径。正确的方法是使用WordPress提供的常量，例如 WP_CONTENT_DIR，它指向 wp-content 目录的绝对文件系统路径。
- mailer()->send() 方法参数不全： send() 方法需要精确的参数列表来正确发送邮件，包括收件人、主题、消息体、邮件头和附件。遗漏或错误传递参数会导致邮件发送失败或附件无法附加。
实现自定义邮件附件的完整代码示例
以下代码演示了如何在订单状态变为“已完成”且支付方式为“货到付款”时，向客户发送一封带有PDF附件的自定义邮件。
/**
* 在WooCommerce订单状态改变时发送带有附件的自定义邮件。
*
* @param int $order_id 订单ID。
* @param string $old_status 订单旧状态。
* @param string $new_status 订单新状态。
* @param WC_Order $order WC_Order 对象。
*/
function action_woocommerce_order_status_changed( $order_id, $old_status, $new_status, $order ) {
// 确保只有在订单状态变为“已完成”且支付方式为“dobirka”（货到付款）时才执行
if ( $new_status == 'completed' && $order->get_payment_method() == 'dobirka' ) {
// 获取WooCommerce邮件发送器实例
$mailer = WC()->mailer();
// 定义邮件接收者、主题和消息体
$to = $order->get_billing_email();
$subject = __( '您的订单已完成，请查收您的礼品！', 'woocommerce' );
$message_body = sprintf(
__( '亲爱的 %s，您的订单 #%s 已成功完成。请查收附件中的礼品。', 'woocommerce' ),
$order->get_billing_first_name(),
$order->get_order_number()
);
// 包装邮件消息，使其符合WooCommerce邮件模板的结构
// 第一个参数是邮件头部标题，第二个是邮件正文内容
$message = $mailer->wrap_message(
sprintf( __( '订单 #%s 已完成', 'woocommerce' ), $order->get_order_number() ),
$message_body
);
// 设置邮件头，确保邮件以HTML格式发送
$headers = 'Content-Type: text/html; charset=UTF-8' . "\r\n";
// 定义附件路径。使用 WP_CONTENT_DIR 常量确保路径正确。
// 假设您的PDF文件位于 wp-content 目录下
$attachments = array( WP_CONTENT_DIR . '/your-gift.pdf' ); // 请将 'your-gift.pdf' 替换为您的实际文件名
// 发送邮件
$mailer->send( $to, $subject, $message, $headers, $attachments );
}
}
// 注册钩子，优先级10，接受4个参数
add_action( 'woocommerce_order_status_changed', 'action_woocommerce_order_status_changed', 10, 4 );
代码解析与注意事项
-
add_action( 'woocommerce_order_status_changed', 'action_woocommerce_order_status_changed', 10, 4 );
- woocommerce_order_status_changed 是一个WooCommerce核心钩子，当订单状态改变时触发。
- action_woocommerce_order_status_changed 是我们自定义的函数名。
- 10 是优先级，数值越小越早执行。
- 4 表示我们的函数将接收4个参数：$order_id, $old_status, $new_status, $order。这比原始问题中的3个参数更完整，因为$order对象直接可用，无需重新实例化。
-
条件判断：if ( $new_status == 'completed' && $order->get_payment_method() == 'dobirka' )
- 确保只有在特定条件下（例如订单完成且支付方式为“货到付款”）才发送邮件，避免不必要的邮件发送。
-
获取邮件发送器：$mailer = WC()->mailer();
- 这是获取WooCommerce邮件发送器实例的推荐方式。
-
邮件内容定义：$to, $subject, $message_body
- $order->get_billing_email() 获取收件人邮箱。
- __('...', 'woocommerce') 用于字符串国际化，推荐在所有面向用户的文本中使用。
- sprintf() 用于格式化字符串，将动态内容（如客户姓名、订单号）插入到消息中。
-
包装邮件消息：$message = $mailer->wrap_message(...)
- 此方法将您的邮件内容包装在WooCommerce的标准邮件模板中，包括页眉和页脚，确保邮件风格一致。第一个参数是邮件的标题（显示在邮件内容顶部），第二个是实际的正文内容。
-
设置邮件头：$headers = 'Content-Type: text/html; charset=UTF-8' . "\r\n";
- 这行代码至关重要，它告诉邮件客户端邮件内容是HTML格式，这样邮件中的HTML标签才能被正确解析。
-
附件路径：$attachments = array( WP_CONTENT_DIR . '/your-gift.pdf' );
- 核心要点： 使用 WP_CONTENT_DIR 常量来构建附件的绝对文件系统路径。WP_CONTENT_DIR 通常指向 wp-content 目录。
- 确保您的附件文件 (your-gift.pdf 在示例中) 确实存在于指定的路径。如果文件在子目录中，例如 wp-content/uploads/gifts/your-gift.pdf，则路径应为 WP_CONTENT_DIR . '/uploads/gifts/your-gift.pdf'。
- 您可以添加多个附件，只需在数组中列出它们的路径。
-
发送邮件：$mailer->send( $to, $subject, $message, $headers, $attachments );
- 确保 send() 方法接收到所有五个参数：收件人、主题、消息体（已包装）、邮件头和附件数组。
部署与调试
- 代码放置位置： 将上述代码放置在您的WordPress子主题的 functions.php 文件中，或者创建一个自定义插件来管理此类功能。不建议直接修改主题文件，因为主题更新会覆盖您的更改。
- 文件权限： 确保您的附件文件具有正确的文件系统权限，以便Web服务器可以读取它们。
-
调试： 如果附件未发送，请检查以下几点：
- 邮件是否成功发送？检查WordPress的邮件日志（如果配置了SMTP插件）。
- 附件路径是否绝对且正确？尝试在代码中 error_log(WP_CONTENT_DIR . '/your-gift.pdf'); 来确认路径是否正确。
- 文件是否存在于该路径？
- 服务器是否允许发送大附件？某些邮件服务提供商对附件大小有限制。
总结
通过遵循本文提供的指南和代码示例，您可以有效地在WooCommerce自定义邮件中集成附件功能。关键在于理解WooCommerce邮件系统的运作方式，使用正确的API调用（WC()->mailer()），并精确指定附件的文件系统路径（利用 WP_CONTENT_DIR）。这将确保您的自定义邮件不仅内容丰富，而且功能完善，为您的客户提供更专业的服务。
