在 WooCommerce 自定义邮件中正确添加附件教程

理解 WooCommerce 邮件系统与附件

在 woocommerce 中发送自定义邮件并附加文件是一项常见的需求，例如在订单完成后向客户发送礼品券 pdf 或发票。woocommerce 提供了一个强大的邮件系统，通过 wc()->mailer() 对象来管理邮件的发送。正确地使用这个对象及其 send() 方法是实现带附件邮件的关键。

在尝试添加附件时，开发者常遇到的问题包括：

1. 错误的附件路径： 文件路径必须是服务器上的绝对路径，而不是相对路径或 URL。
2. 过时或不正确的邮件发送方法： 直接使用 global $woocommerce; $woocommerce->mailer(); 可能会导致一些兼容性问题，推荐使用 WC()->mailer()。
3. send() 方法参数顺序错误： send() 方法有特定的参数顺序，特别是 headers 和 attachments 的位置。
4. 钩子参数不匹配： 自定义钩子函数需要接收正确的参数数量和类型。

实现自定义邮件附件功能

以下是针对 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 );

代码解析与注意事项

1. 钩子 woocommerce_order_status_changed：

   • 此钩子在订单状态发生变化时触发。
   • 它接收四个参数：$order_id, $old_status, $new_status, $order。
   • 在 add_action 中，10 是优先级（默认），4 明确指出回调函数期望接收的参数数量。确保你的函数定义与此匹配。

2. 获取邮件发送器：WC()->mailer()

   • 这是获取 WooCommerce 邮件发送器实例的推荐方式。它比 global $woocommerce; $woocommerce->mailer(); 更简洁且不易出错。

3. 邮件参数：$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: 一个包含附件文件绝对路径的数组。即使只有一个附件，也必须放在数组中。

4. 附件路径：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 目录下，或者你指定的其他任何服务器可访问的绝对路径。

5. 条件判断：

   • 'completed' === $new_status: 检查订单新状态是否为“已完成”。
   • 'dobirka' === $order->get_payment_method(): 检查支付方式是否为“货到付款”。根据你的实际需求调整这些条件。

总结

通过遵循上述指南和示例代码，你可以在 WooCommerce 中可靠地实现自定义邮件附件功能。核心要点在于：使用 WC()->mailer() 获取邮件发送器，正确理解 send() 方法的参数顺序，特别是正确设置 headers 和提供附件的绝对路径。在部署到生产环境之前，务必在开发环境中进行充分的测试，以确保邮件能够正确发送且附件能够正常打开。

以上就是在 WooCommerce 自定义邮件中正确添加附件教程的详细内容，更多请关注php中文网其它相关文章！