如何为WooCommerce自定义邮件添加附件-php教程-PHP中文网

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

聖光之護

发布： 2025-08-07 14:40:21

原创

474人浏览过

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

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

理解WooCommerce自定义邮件与附件

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

核心挑战在于：

正确获取邮件器实例：确保使用WooCommerce推荐的现代方式访问邮件器。
准确指定附件路径：附件路径必须是服务器上的绝对路径，而不是相对路径或URL。
正确调用邮件发送方法：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 );

登录后复制

代码解析

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'。
$mailer->send(...)：
- 这是实际发送邮件的方法。它接受五个参数，顺序非常重要：
  1. $to：收件人邮箱。
  2. $subject：邮件主题。
  3. $message：邮件正文（经过 wrap_message 处理后的HTML内容）。
  4. $headers：邮件头部信息。
  5. $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的开发标准。

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