WordPress源码深度解析之：`wp-includes/pluggable.php`：可插拔函数的设计模式与`if (!function_exists())`的哲学。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷们，晚上好！我是今天的主讲人，很高兴能跟大家一起聊聊WordPress源码中一个非常有趣，但又常常被忽略的文件——wp-includes/pluggable.php。别被“可插拔”这种高大上的名字吓到，其实它的核心思想非常简单，说白了就是WordPress为了让开发者更容易地定制和扩展某些核心功能，搞了一个“备胎机制”。

今天咱们就来扒一扒这个“备胎机制”是如何运作的，以及if (!function_exists())这句代码背后的哲学。

开场白：WordPress的“备胎”策略

想象一下，你开着一辆定制版的汽车，但是汽车制造商给你留了个后门：如果你觉得某些部件不够好，可以自己换一个更牛逼的。pluggable.php就是WordPress给开发者留的这个“后门”。它里面定义了一堆函数，这些函数都是WordPress核心需要用到的，但又允许你用自己的代码去覆盖它们。

第一幕：pluggable.php的结构与内容

打开wp-includes/pluggable.php，你会发现里面几乎全是函数定义，而且每个函数定义都包裹在一个if (!function_exists())的条件判断里。

例如：

if ( ! function_exists( 'wp_mail' ) ) {
    /**
     * Sends an email, similar to PHP's mail function.
     *
     * @since 1.2.1
     *
     * @param string|array $to          Array or comma-separated list of email addresses to send message.
     * @param string       $subject     Email subject.
     * @param string       $message     Message contents.
     * @param string|array $headers     Optional. Additional headers.
     * @param string|array $attachments Optional. Files to attach.
     * @return bool Whether the email contents were sent successfully.
     */
    function wp_mail( $to, $subject, $message, $headers = '', $attachments = array() ) {
        // Default values
        if ( ! isset( $headers ) ) {
            $headers = array();
        }

        // Compact the input array into associative arrays
        if ( is_array( $to ) ) {
            $to = implode( ',', $to );
        }

        // Build the headers
        if ( ! is_array( $headers ) ) {
            $headers = explode( "n", str_replace( "rn", "n", $headers ) );
        }

        // Plugin hook for email.
        $atts = array( 'to' => $to, 'subject' => $subject, 'message' => $message, 'headers' => $headers, 'attachments' => $attachments );

        /**
         * Filters the array of email arguments of wp_mail.
         *
         * @since 2.2.0
         *
         * @param array $atts {
         *     Array of email arguments.
         *
         *     @type string|array $to          Array or comma-separated list of email addresses to send message.
         *     @type string       $subject     Email subject.
         *     @type string       $message     Message contents.
         *     @type string|array $headers     Optional. Additional headers.
         *     @type string|array $attachments Optional. Files to attach.
         * }
         */
        $atts = apply_filters( 'wp_mail', $atts );

        $to      = $atts['to'];
        $subject = $atts['subject'];
        $message = $atts['message'];
        $headers = $atts['headers'];
        $attachments = $atts['attachments'];

        if ( ! is_array( $attachments ) ) {
            $attachments = explode( "n", str_replace( "rn", "n", $attachments ) );
        }

        // If no recipient, don't bother.
        if ( empty( $to ) ) {
            return false;
        }

        // Copy missing data to the compact one.
        $compact = compact( 'to', 'subject', 'message', 'headers', 'attachments' );

        /**
         * Filters the wp_mail() arguments.
         *
         * @since 3.9.0
         *
         * @param array $compact Compact array of arguments for wp_mail().
         */
        $compact = apply_filters( 'wp_mail_args', $compact );

        $to        = $compact['to'];
        $subject   = $compact['subject'];
        $message   = $compact['message'];
        $headers   = $compact['headers'];
        $attachments = $compact['attachments'];

        if ( defined( 'WP_MAIL_FROM' ) ) {
            $from_email = WP_MAIL_FROM;
        } else {
            // Get the site domain and get rid of www.
            $sitename = strtolower( $_SERVER['SERVER_NAME'] );
            if ( substr( $sitename, 0, 4 ) == 'www.' ) {
                $sitename = substr( $sitename, 4 );
            }

            $from_email = 'wordpress@' . $sitename;
        }

        /**
         * Filters the email address to send from.
         *
         * @since 2.2.0
         *
         * @param string $from_email Email address to send from.
         */
        $from_email = apply_filters( 'wp_mail_from', $from_email );

        if ( defined( 'WP_MAIL_FROM_NAME' ) ) {
            $from_name = WP_MAIL_FROM_NAME;
        } else {
            $from_name = 'WordPress';
        }

        /**
         * Filters the name to send from.
         *
         * @since 2.3.0
         *
         * @param string $from_name Name to send from.
         */
        $from_name = apply_filters( 'wp_mail_from_name', $from_name );

        $phpmailer = new PHPMailer( true );

        try {
            // Tell PHPMailer to use SMTP
            $phpmailer->isSMTP();

            // Enable SMTP debugging
            // SMTP::DEBUG_OFF = off (for production use)
            // SMTP::DEBUG_CLIENT = client messages
            // SMTP::DEBUG_SERVER = client and server messages
            $phpmailer->SMTPDebug = SMTP::DEBUG_OFF;

            //Set the hostname of the mail server
            $phpmailer->Host = SMTP_HOST;

            //Set the SMTP port number - likely to be 25, 465 or 587
            $phpmailer->Port = SMTP_PORT;

            //Whether to use SMTP authentication
            $phpmailer->SMTPAuth = SMTP_AUTH;

            //Username to use for SMTP authentication
            $phpmailer->Username = SMTP_USER;

            //Password to use for SMTP authentication
            $phpmailer->Password = SMTP_PASSWORD;

            //Set the encryption system to use - ssl (deprecated) or tls
            $phpmailer->SMTPSecure = SMTP_SECURE;

            //Server settings
            $phpmailer->SMTPAutoTLS = false;

            // Set From:
            $phpmailer->setFrom( $from_email, $from_name, false );

            // Set To:
            $emails = explode( ',', $to );

            foreach ( $emails as $email ) {
                $email = trim( $email );
                if ( is_email( $email ) ) {
                    $phpmailer->addAddress( $email );
                }
            }

            // Set Subject
            $phpmailer->Subject = $subject;

            // Set Body
            $phpmailer->Body = $message;
            $phpmailer->AltBody = strip_tags( $message );
            $phpmailer->isHTML( true );

            // Add attachments
            foreach ( $attachments as $attachment ) {
                if ( file_exists( $attachment ) ) {
                    $phpmailer->addAttachment( $attachment );
                }
            }

            // Send the email
            $result = $phpmailer->send();
            return $result;

        } catch ( Exception $e ) {
            error_log( 'WordPress e-mail error: ' . $phpmailer->ErrorInfo );
            return false;
        }
    }
}

可以看到，这段代码定义了一个wp_mail函数，用于发送邮件。但它被if ( ! function_exists( 'wp_mail' ) )包裹着。这意味着：

WordPress启动时，会检查是否已经定义了wp_mail函数。
如果没有定义，WordPress才会加载并使用pluggable.php里提供的wp_mail函数。
如果已经定义了，WordPress就跳过这段代码，使用你自定义的wp_mail函数。

第二幕：if (!function_exists())的哲学

这句代码是整个“可插拔”机制的核心，它体现了一种开放、灵活的设计哲学：

拥抱定制化： WordPress知道每个网站的需求都不一样，与其强行规定某些功能的实现方式，不如允许开发者根据自己的需要进行定制。
保持核心简洁： WordPress核心代码只需要提供最基本的功能，更高级、更特殊的功能交给插件或主题去实现，这样可以避免核心代码过于臃肿。
降低维护成本： 如果某个核心函数需要修改，WordPress只需要修改pluggable.php里的版本，而不需要担心会影响到已经使用自定义函数的开发者。

第三幕：如何“插拔”函数

要“插拔”pluggable.php里的函数，你需要做的很简单：

在你的主题的functions.php文件或者插件里，定义一个与pluggable.php里同名的函数。
确保你的函数在pluggable.php之前加载。

WordPress加载文件的顺序大致是：

wp-config.php
wp-settings.php (加载核心文件，包括pluggable.php)
主题的functions.php
插件

所以，为了确保你的函数优先加载，你需要使用一些技巧。一般来说，有两种方法：

使用plugins_loaded钩子： plugins_loaded钩子会在所有插件加载完毕后触发，你可以把你的函数定义放在这个钩子的回调函数里。

add_action( 'plugins_loaded', 'my_custom_wp_mail' );

function my_custom_wp_mail() {
    if ( ! function_exists( 'wp_mail' ) ) {
        function wp_mail( $to, $subject, $message, $headers = '', $attachments = array() ) {
            // 你的自定义代码
            error_log('Using my custom wp_mail function!');
            return true; // 假设发送成功
        }
    }
}

注意： 这种方法仍然需要在plugins_loaded钩子里面判断function_exists('wp_mail')，因为其他插件也可能尝试覆盖wp_mail函数。

使用 MU (Must-Use) 插件： MU插件是WordPress启动时最先加载的插件，你可以把你的函数定义放在一个MU插件里，这样就能确保你的函数在pluggable.php之前加载。 MU插件放在wp-content/mu-plugins目录下。
```
// wp-content/mu-plugins/my-custom-functions.php
if ( ! function_exists( 'wp_mail' ) ) {
    function wp_mail( $to, $subject, $message, $headers = '', $attachments = array() ) {
        // 你的自定义代码
        error_log('Using my custom wp_mail function!');
        return true; // 假设发送成功
    }
}
```
使用MU插件的好处是不需要使用plugins_loaded钩子，因为MU插件总是最先加载的。

第四幕：常见的可插拔函数

pluggable.php里有很多常用的函数，以下是一些例子：

函数名	功能
`wp_mail`	发送邮件
`wp_set_auth_cookie`	设置用户认证cookie
`wp_validate_auth_cookie`	验证用户认证cookie
`wp_redirect`	重定向页面
`wp_safe_redirect`	安全重定向页面 (会检查URL的安全性)
`wp_die`	显示错误信息并退出执行
`auth_redirect`	如果用户未登录，则重定向到登录页面
`check_admin_referer`	检查管理界面的nonce值，防止CSRF攻击
`get_currentuserinfo`	获取当前用户信息 (已弃用，建议使用`wp_get_current_user`)
`wp_login`	用户登录 (不推荐直接使用，应该使用`wp_signon`)

第五幕：实战案例：自定义wp_mail函数

假设你需要使用一个第三方的邮件服务提供商（比如SendGrid、Mailgun）来发送邮件，而不是WordPress默认的wp_mail函数。你可以这样做：

安装并配置SendGrid/Mailgun的PHP SDK。
在你的主题的functions.php文件或者一个MU插件里，定义你自己的wp_mail函数。

// 使用SendGrid发送邮件的例子 (需要先安装SendGrid的PHP SDK)

if ( ! function_exists( 'wp_mail' ) ) {
    function wp_mail( $to, $subject, $message, $headers = '', $attachments = array() ) {
        require_once 'vendor/autoload.php'; // 引入SendGrid的autoload文件

        $email = new SendGridMailMail();
        $email->setFrom("[email protected]", "Your Name");
        $email->setSubject($subject);
        $email->addTo($to);
        $email->addContent("text/plain", strip_tags($message));
        $email->addContent("text/html", $message);

        $sendgrid = new SendGrid(getenv('SENDGRID_API_KEY')); // 从环境变量中获取API Key
        try {
            $response = $sendgrid->send($email);
            //print $response->statusCode() . "n";
            //print_r($response->headers());
            //print $response->body() . "n";

            if ($response->statusCode() >= 200 && $response->statusCode() < 300) {
                return true; // 发送成功
            } else {
                error_log('SendGrid error: ' . $response->body());
                return false; // 发送失败
            }

        } catch (Exception $e) {
            error_log('Caught exception: '. $e->getMessage() ."n");
            return false; // 发送失败
        }
    }
}

关键点：

你需要引入第三方邮件服务提供商的PHP SDK，并根据他们的文档配置好API Key等信息。
你的自定义wp_mail函数需要接收和WordPress默认wp_mail函数相同的参数，并使用第三方SDK来发送邮件。
你需要处理发送成功和失败的情况，并返回true或false。

第六幕：注意事项

命名冲突： 确保你的自定义函数名不会与其他插件或主题里的函数冲突。
参数兼容性： 你的自定义函数应该接收和WordPress默认函数相同的参数，并且参数类型也要兼容。
性能： 如果你的自定义函数性能很差，可能会影响网站的整体性能。
更新： 当WordPress更新时，你可能需要检查你的自定义函数是否仍然兼容最新的WordPress版本。

总结：pluggable.php的价值

pluggable.php和if (!function_exists())的设计模式，是WordPress灵活性的重要体现。它允许开发者在不修改核心代码的情况下，定制和扩展某些核心功能，从而满足各种各样的需求。

虽然这种机制带来了很多好处，但也需要注意一些潜在的问题，比如命名冲突、参数兼容性等。只要你遵循一些基本的规则，就能充分利用pluggable.php的强大功能，打造一个更加个性化、更加强大的WordPress网站。

希望今天的讲座对大家有所帮助。谢谢大家！

发表回复 取消回复

发表回复取消回复