理解WooCommerce自定义邮件与附件
在WooCommerce中，当需要根据特定事件（如订单状态变更）发送定制邮件时，通常会使用add_action钩子来触发自定义函数。为这些邮件添加附件是常见的需求，例如发送PDF格式的礼品券、发票或产品手册。然而，直接添加附件可能会遇到路径不正确或邮件器使用方式过时的问题。
核心挑战在于：
- 正确获取邮件器实例：确保使用WooCommerce推荐的现代方式访问邮件器。
- 准确指定附件路径：附件路径必须是服务器上的绝对路径，而不是相对路径或URL。
- 正确调用邮件发送方法：send()方法需要正确的参数顺序，包括收件人、主题、消息、头部信息以及附件数组。
核心代码实现
以下是为WooCommerce订单状态变更时发送自定义邮件并附带附件的正确实现方式。
代码示例
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 );代码解析
-
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”（货到付款）时，才执行邮件发送逻辑。您可以根据自己的业务逻辑修改这些条件。
-
$mailer = WC()->mailer();：
- 这是获取WooCommerce邮件器实例的推荐方式。WC() 是WooCommerce核心的全局函数，返回WooCommerce的主实例，通过它调用 mailer() 方法即可获得邮件器对象。这比使用 global $woocommerce; $woocommerce->mailer(); 更简洁和现代化。
-
邮件参数配置：
- $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编码。
-
附件路径：
- $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'。
- $attachments = array( WP_CONTENT_DIR . '/file.pdf' );：这是关键部分。
-
$mailer->send(...)：
- 这是实际发送邮件的方法。它接受五个参数，顺序非常重要：
- $to：收件人邮箱。
- $subject：邮件主题。
- $message：邮件正文（经过 wrap_message 处理后的HTML内容）。
- $headers：邮件头部信息。
- $attachments：一个包含所有附件绝对路径的数组。
- 这是实际发送邮件的方法。它接受五个参数，顺序非常重要：
-
add_action( 'woocommerce_order_status_changed', 'action_woocommerce_order_status_changed_with_attachment', 10, 4 );：
- 注册钩子，将您的函数与 woocommerce_order_status_changed 事件关联起来。
- 10 是优先级，表示您的函数在其他相同钩子的函数之后执行（默认优先级）。
- 4 是关键，它告诉WordPress您的函数期望接收4个参数。如果这里参数数量不匹配，您的函数可能无法正确获取 $order 对象。
注意事项与最佳实践
-
文件路径的准确性：
- 始终使用绝对路径来指定附件。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 ) );。
-
使用现代WooCommerce API：
- 优先使用 WC()->mailer() 而不是 global $woocommerce; $woocommerce->mailer();。前者是更现代、更推荐的访问WooCommerce核心组件的方式。
- 直接使用钩子传递的 $order 对象，而不是通过 $order_id 再次实例化 new WC_Order( $order_id )，这样可以避免重复操作，提高效率。
-
国际化与可翻译性：
- 在所有面向用户的字符串中，使用 __( 'Your Text', 'your-text-domain' ) 或 _e( 'Your Text', 'your-text-domain' ) 进行文本域包装。这使得您的代码可以被翻译成多种语言，提高插件或主题的可用性。请将 'your-text-domain' 替换为您自己插件或主题的文本域。
-
调试与测试：
- 在开发环境中，务必进行充分测试。模拟订单状态变更，检查邮件是否发送成功，附件是否正确附加。
- 如果邮件未发送或附件有问题，检查WordPress的错误日志（通常在 wp-content/debug.log，如果 WP_DEBUG 和 WP_DEBUG_LOG 已启用），或使用插件（如WP Mail SMTP）来辅助调试邮件发送问题。
总结
通过遵循本文提供的代码示例和最佳实践，您可以有效地在WooCommerce自定义邮件中添加附件。核心在于理解邮件器的工作原理、正确构建附件的绝对路径，以及利用WooCommerce现代API进行开发。这不仅能满足业务需求，还能确保您的代码健壮、可维护且符合WordPress和WooCommerce的开发标准。
