理解 WooCommerce 邮件系统与附件
在 woocommerce 中发送自定义邮件并附加文件是一项常见的需求，例如在订单完成后向客户发送礼品券 pdf 或发票。woocommerce 提供了一个强大的邮件系统，通过 wc()->mailer() 对象来管理邮件的发送。正确地使用这个对象及其 send() 方法是实现带附件邮件的关键。
在尝试添加附件时，开发者常遇到的问题包括：
- 错误的附件路径： 文件路径必须是服务器上的绝对路径，而不是相对路径或 URL。
- 过时或不正确的邮件发送方法： 直接使用 global $woocommerce; $woocommerce->mailer(); 可能会导致一些兼容性问题，推荐使用 WC()->mailer()。
- send() 方法参数顺序错误： send() 方法有特定的参数顺序，特别是 headers 和 attachments 的位置。
- 钩子参数不匹配： 自定义钩子函数需要接收正确的参数数量和类型。
实现自定义邮件附件功能
以下是针对 WooCommerce 订单状态变更时发送带附件邮件的正确实现方法。我们将以订单状态变为“已完成”且支付方式为“货到付款”（dobirka）为例。
/**
* 在 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_with_attachment( $order_id, $old_status, $new_status, $order ) {
// 检查订单是否已完成且支付方式为 'dobirka'
if ( 'completed' === $new_status && 'dobirka' === $order->get_payment_method() ) {
// 获取 WooCommerce 邮件发送器实例
$mailer = WC()->mailer();
// 邮件接收者、主题和消息体
$to = $order->get_billing_email();
$subject = sprintf( __( '您的订单 #%s 已完成 - 附赠礼品', 'woocommerce' ), $order->get_order_number() );
$message_body = sprintf( __( '亲爱的 %s，您的订单已完成，感谢您的惠顾！随信附上您的专属礼品。', 'woocommerce' ), $order->get_billing_first_name() );
// 包装邮件消息（包含邮件头和消息体）
// 第一个参数通常是邮件的标题或介绍，第二个参数是实际的消息内容。
$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 是 WordPress 内容目录的绝对路径常量，例如 /var/www/html/wp-content
// 请确保 'file.pdf' 实际存在于 wp-content 目录下，并替换为你的实际文件路径
$attachments = array( WP_CONTENT_DIR . '/your-gift-file.pdf' ); // 替换为你的 PDF 文件名
// 发送邮件
$mailer->send( $to, $subject, $message, $headers, $attachments );
}
}
// 注册钩子，确保函数接收到所有必要的参数 (10 是优先级，4 是参数数量)
add_action( 'woocommerce_order_status_changed', 'action_woocommerce_order_status_changed_with_attachment', 10, 4 );
代码解析与注意事项
-
钩子 woocommerce_order_status_changed：
- 此钩子在订单状态发生变化时触发。
- 它接收四个参数：$order_id, $old_status, $new_status, $order。
- 在 add_action 中，10 是优先级（默认），4 明确指出回调函数期望接收的参数数量。确保你的函数定义与此匹配。
-
获取邮件发送器：WC()->mailer()
- 这是获取 WooCommerce 邮件发送器实例的推荐方式。它比 global $woocommerce; $woocommerce->mailer(); 更简洁且不易出错。
-
邮件参数：$mailer->send()
- send() 方法的完整签名通常是：send( $to, $subject, $message, $headers, $attachments )。
- $to: 收件人邮箱地址。
- $subject: 邮件主题。
- $message: 邮件内容，通常由 mailer->wrap_message() 生成，它会添加标准的 WooCommerce 邮件模板头部和尾部。
- $headers: 邮件头信息。非常重要，如果邮件内容是 HTML，必须包含 'Content-Type: text/html; charset=UTF-8'。注意使用 "\r\n" 作为换行符。
- $attachments: 一个包含附件文件绝对路径的数组。即使只有一个附件，也必须放在数组中。
-
附件路径：WP_CONTENT_DIR
- WP_CONTENT_DIR 是 WordPress 定义的一个常量，表示 wp-content 目录的服务器绝对路径。例如，如果你的 WordPress 安装在 /var/www/html/，那么 WP_CONTENT_DIR 可能是 /var/www/html/wp-content。
- 切勿使用相对路径或 URL，邮件系统需要直接访问服务器上的文件。
- 确保你的 PDF 文件（例如 your-gift-file.pdf）确实位于 wp-content 目录下，或者你指定的其他任何服务器可访问的绝对路径。
-
条件判断：
- 'completed' === $new_status: 检查订单新状态是否为“已完成”。
- 'dobirka' === $order->get_payment_method(): 检查支付方式是否为“货到付款”。根据你的实际需求调整这些条件。
总结
通过遵循上述指南和示例代码，你可以在 WooCommerce 中可靠地实现自定义邮件附件功能。核心要点在于：使用 WC()->mailer() 获取邮件发送器，正确理解 send() 方法的参数顺序，特别是正确设置 headers 和提供附件的绝对路径。在部署到生产环境之前，务必在开发环境中进行充分的测试，以确保邮件能够正确发送且附件能够正常打开。
