如何为WooCommerce自定义邮件添加附件

本文详细介绍了如何在WooCommerce中为自定义触发的邮件添加附件。通过利用WooCommerce内置的邮件器（Mailer）功能，并结合正确的钩子、参数传递以及文件路径配置，您可以确保附件能够成功随邮件发送给客户，同时遵循WooCommerce的现代开发实践。

理解WooCommerce自定义邮件与附件

在WooCommerce中，当需要根据特定事件（如订单状态变更）发送定制邮件时，通常会使用add_action钩子来触发自定义函数。为这些邮件添加附件是常见的需求，例如发送PDF格式的礼品券、发票或产品手册。然而，直接添加附件可能会遇到路径不正确或邮件器使用方式过时的问题。

核心挑战在于：

1. 正确获取邮件器实例：确保使用WooCommerce推荐的现代方式访问邮件器。
2. 准确指定附件路径：附件路径必须是服务器上的绝对路径，而不是相对路径或URL。
3. 正确调用邮件发送方法：send()方法需要正确的参数顺序，包括收件人、主题、消息、头部信息以及附件数组。

核心代码实现

以下是为WooCommerce订单状态变更时发送自定义邮件并附带附件的正确实现方式。

代码示例

<?php /**  * 为WooCommerce订单完成邮件添加附件  * 当订单状态变为“已完成”且支付方式为“货到付款”时触发  */ function action_woocommerce_order_status_changed_with_attachment( $order_id, $old_status, $new_status, $order ) {     // 确保仅在订单状态从任意状态变为“已完成”且支付方式为“货到付款”时执行     if ( $new_status === 'completed' && $order->get_payment_method() === 'dobirka' ) {         // 获取WooCommerce邮件器实例         $mailer = WC()->mailer();          // 定义邮件接收者、主题和消息体         $to = $order->get_billing_email();         $subject = sprintf( __( '您的订单 #%s 已完成 - 附赠礼品', 'your-text-domain' ), $order->get_order_number() );         $message_body = sprintf(              __( '亲爱的 %s，您的订单 #%s 已成功完成。感谢您的购买！我们随邮件附赠了一份小礼品，请查收。', 'your-text-domain' ),              $order->get_billing_first_name(),             $order->get_order_number()         );          // 包装邮件内容，包含邮件头部信息         // 第一个参数是邮件头，第二个参数是邮件体         $message = $mailer->wrap_message(              sprintf( __( '订单 %s 已完成', 'your-text-domain' ), $order->get_order_number() ),              $message_body          );          // 定义邮件头部，通常用于指定内容类型         $headers = 'Content-Type: text/html; charset=UTF-8';          // 定义附件路径         // WP_CONTENT_DIR 是 WordPress 内容目录的绝对路径，例如 /var/www/html/wp-content/         // 确保文件 'file.pdf' 实际存在于 wp-content 目录下         $attachments = array( WP_CONTENT_DIR . '/file.pdf' ); // 请替换为您的实际文件路径和文件名          // 发送邮件         // send 方法参数顺序: $to, $subject, $message, $headers, $attachments         $mailer->send( $to, $subject, $message, $headers, $attachments );     } } // 注册动作钩子 // 10 是优先级，4 是函数接受的参数数量 ($order_id, $old_status, $new_status, $order) add_action( 'woocommerce_order_status_changed', 'action_woocommerce_order_status_changed_with_attachment', 10, 4 );

代码解析

1. action_woocommerce_order_status_changed_with_attachment 函数：

   • 此函数通过 woocommerce_order_status_changed 钩子在订单状态发生变化时被调用。
   • 它接收四个参数：$order_id（订单ID）、$old_status（旧状态）、$new_status（新状态）和 $order（WC_Order 对象实例）。直接获取 $order 对象是现代WooCommerce开发中的推荐做法，避免了旧版中通过 $order_id 重新实例化。
   • if ( $new_status === ‘completed’ && $order->get_payment_method() === ‘dobirka’ )：这是一个条件判断，确保只有当订单状态变为“已完成”且支付方式为“dobirka”（货到付款）时，才执行邮件发送逻辑。您可以根据自己的业务逻辑修改这些条件。

2. $mailer = WC()->mailer();：

   • 这是获取WooCommerce邮件器实例的推荐方式。WC() 是WooCommerce核心的全局函数，返回WooCommerce的主实例，通过它调用 mailer() 方法即可获得邮件器对象。这比使用 global $woocommerce; $woocommerce->mailer(); 更简洁和现代化。

3. 邮件参数配置：

   • $to = $order->get_billing_email();：获取订单的账单邮箱作为收件人。
   • $subject 和 $message_body：定义邮件的主题和正文内容。使用 sprintf() 可以方便地插入动态数据，如订单号和客户姓名。
   • $message = $mailer->wrap_message(…)：此方法用于将邮件的“头部”（在邮件客户端中通常显示为订单号或摘要）与实际的 $message_body 结合，形成完整的HTML邮件内容。
   • $headers = ‘Content-Type: text/html; charset=UTF-8’;：定义邮件的MIME头部，告知邮件客户端邮件内容是HTML格式，并使用UTF-8编码。

4. 附件路径：

   • $attachments = array( WP_CONTENT_DIR . ‘/file.pdf’ );：这是关键部分。
     • WP_CONTENT_DIR 是WordPress定义的一个常量，它指向WordPress安装目录下的 wp-content 文件夹的绝对路径。例如，如果您的WordPress安装在 /var/www/html/，那么 WP_CONTENT_DIR 可能是 /var/www/html/wp-content。
     • 重要提示：附件路径必须是服务器上的绝对路径，而不是相对路径或可访问的URL。确保您要附加的文件（例如 file.pdf）实际存在于指定的路径中。如果您的文件在 wp-content/uploads/2023/10/my-gift.pdf，那么路径应为 WP_CONTENT_DIR . ‘/uploads/2023/10/my-gift.pdf’。

5. $mailer->send(…)：

   • 这是实际发送邮件的方法。它接受五个参数，顺序非常重要：
     1. $to：收件人邮箱。
     2. $subject：邮件主题。
     3. $message：邮件正文（经过 wrap_message 处理后的HTML内容）。
     4. $headers：邮件头部信息。
     5. $attachments：一个包含所有附件绝对路径的数组。

6. add_action( ‘woocommerce_order_status_changed’, ‘action_woocommerce_order_status_changed_with_attachment’, 10, 4 );：

   • 注册钩子，将您的函数与 woocommerce_order_status_changed 事件关联起来。
   • 10 是优先级，表示您的函数在其他相同钩子的函数之后执行（默认优先级）。
   • 4 是关键，它告诉WordPress您的函数期望接收4个参数。如果这里参数数量不匹配，您的函数可能无法正确获取 $order 对象。

注意事项与最佳实践

1. 文件路径的准确性：

   • 始终使用绝对路径来指定附件。WP_CONTENT_DIR 是一个非常有用的常量，但请确保您的文件确实位于该常量指向的目录下的子目录中。
   • 对于上传的文件（通常在 wp-content/uploads），您可以使用 wp_upload_dir() 函数来获取上传目录的信息，然后构建路径。例如：

     $upload_dir = wp_upload_dir(); $attachment_path = $upload_dir['basedir'] . '/your-custom-folder/your-file.pdf'; $attachments = array( $attachment_path );
   • 在开发环境中，可以尝试打印 $attachments 数组来确认路径是否正确，例如 error_log( print_r( $attachments, true ) );。

2. 使用现代WooCommerce API：

   • 优先使用 WC()->mailer() 而不是 global $woocommerce; $woocommerce->mailer();。前者是更现代、更推荐的访问WooCommerce核心组件的方式。
   • 直接使用钩子传递的 $order 对象，而不是通过 $order_id 再次实例化 new WC_Order( $order_id )，这样可以避免重复操作，提高效率。

3. 国际化与可翻译性：

   • 在所有面向用户的字符串中，使用 __( ‘Your Text’, ‘your-text-domain’ ) 或 _e( ‘Your Text’, ‘your-text-domain’ ) 进行文本域包装。这使得您的代码可以被翻译成多种语言，提高插件或主题的可用性。请将 ‘your-text-domain’ 替换为您自己插件或主题的文本域。

4. 调试与测试：

   • 在开发环境中，务必进行充分测试。模拟订单状态变更，检查邮件是否发送成功，附件是否正确附加。
   • 如果邮件未发送或附件有问题，检查WordPress的错误日志（通常在 wp-content/debug.log，如果 WP_DEBUG 和 WP_DEBUG_LOG 已启用），或使用插件（如WP Mail SMTP）来辅助调试邮件发送问题。

总结

通过遵循本文提供的代码示例和最佳实践，您可以有效地在WooCommerce自定义邮件中添加附件。核心在于理解邮件器的工作原理、正确构建附件的绝对路径，以及利用WooCommerce现代API进行开发。这不仅能满足业务需求，还能确保您的代码健壮、可维护且符合WordPress和WooCommerce的开发标准。