深入理解 WordPress `pluggable.php` 的源码设计：为何其中的函数可以被插件重写，以及其优缺点。

各位观众，晚上好！我是今天的讲师，很高兴能和大家一起聊聊 WordPress 里面那个有点神秘，又非常重要的 pluggable.php 文件。

今天我们不搞虚的，直接深入源码，扒一扒它的设计思路，以及为什么它里面的函数可以被插件“截胡”，还有这种设计的优缺点，当然，还会用代码说话，让大家看得明白，听得清楚。

开场白：谁动了我的函数？

相信很多 WordPress 开发者都遇到过这种情况：明明 WordPress 核心里有某个函数，但我们在插件里定义了同名函数，结果运行的时候，WordPress 却执行了我们插件里的函数。是不是有点懵？这背后就是 pluggable.php 在搞事情。

pluggable.php 是个啥？

简单来说，pluggable.php 里面放着一些可以被插件覆盖（override）的函数。 这些函数通常是一些比较通用，但又有可能需要根据不同情况进行定制的功能。

核心机制：条件判断 + 函数定义

pluggable.php 的核心机制其实非常简单：它会在定义函数之前，先判断一下同名函数是否已经存在。如果不存在，就定义这个函数；如果已经存在，就什么也不做。

我们来看一个典型的例子，比如 wp_mail() 函数，这个函数负责发送邮件。在 wp-includes/pluggable.php 里，你会看到类似这样的代码：

if ( ! function_exists( 'wp_mail' ) ) {
    /**
     * Send an email, similar to PHP's mail function.
     *
     * @since 1.2.1
     *
     * @param string|string[] $to          Array or comma-separated list of email addresses to send message.
     * @param string          $subject     Email subject.
     * @param string          $message     Message contents.
     * @param string|string[] $headers     Optional. Additional headers.
     * @param string|string[] $attachments Optional. Files to attach.
     * @return bool Whether the email contents were sent successfully.
     */
    function wp_mail( $to, $subject, $message, $headers = '', $attachments = array() ) {
        // 邮件发送的具体逻辑
        // ...
        return true; // 或者 false，表示发送成功或失败
    }
}

这段代码的核心就在 if ( ! function_exists( 'wp_mail' ) ) 这一句。 它的意思是：如果 wp_mail 这个函数 不存在 ，那么就定义它。 如果 wp_mail 已经存在了（比如被某个插件定义过了），那么就 什么也不做 。

插件如何“截胡”？

要覆盖 pluggable.php 里的函数，只需要在你的插件里定义一个同名函数，并且确保你的插件比 WordPress 核心代码更早加载。

WordPress 的插件加载顺序是有规律的，通常按照插件目录名称的字母顺序加载。 所以，如果你想覆盖某个 pluggable.php 里的函数，可以尝试修改你的插件目录名称，让它排在 WordPress 核心代码之前加载。

一个简单的例子：

假设我们想修改 wp_mail() 函数，让它在发送邮件之前，先记录一下日志。 我们可以在插件里这样写：

<?php
/**
 * Plugin Name: Custom WP Mail
 * Description: Override wp_mail function for logging.
 */

if ( ! function_exists( 'wp_mail' ) ) {
    function wp_mail( $to, $subject, $message, $headers = '', $attachments = array() ) {
        // 记录日志
        error_log( 'Sending email to: ' . $to . ', subject: ' . $subject );

        // 调用 WordPress 核心的 wp_mail 函数（可选）
        // 如果不调用，就完全取代了 WordPress 的邮件发送逻辑
        // 注意，这里避免了无限递归调用
        require_once ABSPATH . WPINC . '/pluggable.php'; // 确保pluggable.php被包含
        if ( function_exists( 'wp_mail' ) && __FUNCTION__ !== 'wp_mail_custom' ) {
            return wp_mail_custom( $to, $subject, $message, $headers, $attachments ); // 使用自定义名称
        } else {
            // 原始的 wp_mail 逻辑，如果之前的 wp_mail 被移除或不可用
            // 这里需要模拟原始的 wp_mail 行为，或者抛出错误
            error_log( 'Original wp_mail function is missing!' );
            return false;
        }
    }

    //为了避免与内置函数冲突，重命名自定义函数
    if(!function_exists('wp_mail_custom')){
        function wp_mail_custom( $to, $subject, $message, $headers = '', $attachments = array() ) {
            // 记录日志
            error_log( 'Sending email to: ' . $to . ', subject: ' . $subject );

            // 调用 WordPress 核心的 wp_mail 函数（可选）
            // 如果不调用，就完全取代了 WordPress 的邮件发送逻辑
            // 注意，这里避免了无限递归调用

            //模拟原始的 wp_mail 行为
            $phpmailer = new PHPMailer(true);
            try {
                $phpmailer->setFrom('[email protected]', 'Your Name'); // 设置发件人
                $phpmailer->addAddress($to);     // 添加收件人
                $phpmailer->Subject = $subject;  // 设置主题
                $phpmailer->Body    = $message;  // 设置邮件正文
                $phpmailer->send();
                return true;
            } catch (Exception $e) {
                error_log("Message could not be sent. Mailer Error: {$phpmailer->ErrorInfo}");
                return false;
            }
        }
    }

}

在这个例子中，我们定义了一个 wp_mail 函数，它首先记录日志，然后调用 WordPress 核心的 wp_mail 函数（为了避免无限递归，我们把自定义的函数重命名为wp_mail_custom，再调用原来的函数）。

pluggable.php 的优缺点

这种设计模式，就像一把双刃剑，既有优点，也有缺点。

优点：

• 灵活性： 允许开发者根据自己的需求，修改 WordPress 的核心功能，而无需修改 WordPress 的核心代码。 这大大提高了 WordPress 的灵活性和可扩展性。
• 定制性： 开发者可以轻松地定制 WordPress 的行为，以满足特定的需求。 例如，可以修改邮件发送方式、用户认证方式等等。
• 易于维护： 由于修改是在插件中进行的，所以升级 WordPress 核心时，不会影响到这些修改。 这样可以减少维护成本。

缺点：

• 冲突风险： 如果多个插件都覆盖了同一个 pluggable.php 里的函数，就可能发生冲突。 哪个插件的函数先生效，取决于插件的加载顺序，这可能会导致不可预测的结果。
• 可维护性： 过度依赖 pluggable.php 可能会导致代码难以维护。 因为 WordPress 的行为被分散到了各个插件中，使得代码的整体结构变得复杂。
• 性能问题： 每次调用 pluggable.php 里的函数时，都需要先判断函数是否已经被覆盖。 虽然这个判断很快，但在高并发的情况下，也可能会对性能产生一定的影响。
• 依赖顺序： 插件的加载顺序至关重要，如果顺序不对，覆盖可能不生效。这会增加开发者的心智负担，需要对WordPress的加载机制有深入的理解。
• 潜在的安全风险 如果插件开发者对覆盖的函数理解不够深入，或者编写的代码存在漏洞，可能会引入安全风险。

我们用表格来总结一下：

优点	缺点
灵活性	冲突风险：多个插件覆盖同一函数可能导致冲突。
定制性	可维护性：过度依赖使代码难以维护，行为分散。
易于维护	性能问题：每次调用需判断函数是否被覆盖，高并发时可能影响性能。
无需改核心代码	依赖顺序：插件加载顺序至关重要，顺序错误覆盖不生效。
	潜在的安全风险：若插件开发者对覆盖函数理解不够深入，或者编写的代码存在漏洞，可能会引入安全风险。

最佳实践

既然 pluggable.php 有这么多优缺点，那么在使用它的时候，应该注意哪些问题呢？

• 谨慎使用： 只有在确实需要修改 WordPress 核心功能的情况下，才考虑使用 pluggable.php 。 尽量使用 WordPress 提供的 action 和 filter 钩子，而不是直接覆盖函数。
• 避免冲突： 在覆盖函数之前，先仔细检查是否已经有其他插件覆盖了同一个函数。 可以使用 function_exists() 函数来判断函数是否已经存在。
• 注意顺序： 确保你的插件在 WordPress 核心代码之前加载。 可以通过修改插件目录名称来实现。
• 做好备份： 在修改 pluggable.php 里的函数之前，一定要做好备份。 这样可以防止出现意外情况，导致 WordPress 无法正常运行。
• 代码规范： 编写高质量的代码，避免出现错误和漏洞。 确保你的代码易于阅读和维护。
• 充分测试： 在发布插件之前，一定要进行充分的测试。 确保你的插件能够正常工作，并且不会与其他插件产生冲突。
• 提供钩子 如果你的插件覆盖了某个 pluggable.php 里的函数，最好提供一些 action 和 filter 钩子，让其他开发者可以对你的插件进行定制。
• 版本控制 在覆盖函数之前，查看函数的版本号，确保你的代码与 WordPress 核心代码兼容。 不同的 WordPress 版本，pluggable.php 里的函数可能会有所不同。
• 命名空间 为了避免与其他插件的函数冲突，可以使用命名空间来管理你的函数。

一个更复杂的例子：自定义用户认证

假设我们想实现一个自定义的用户认证系统，不使用 WordPress 默认的用户名和密码，而是使用手机验证码登录。 这时，我们就需要覆盖 wp_authenticate() 函数。

<?php
/**
 * Plugin Name: Custom Authentication
 * Description: Use phone number and verification code for login.
 */

if ( ! function_exists( 'wp_authenticate' ) ) {
    function wp_authenticate( $username, $password ) {
        // 验证手机号码和验证码
        $user = validate_phone_number_and_code( $username, $password );

        if ( is_wp_error( $user ) ) {
            return $user;
        }

        return $user;
    }
}

/**
 * Validate phone number and verification code.
 *
 * @param string $phone_number Phone number.
 * @param string $code         Verification code.
 * @return WP_User|WP_Error User object or WP_Error object.
 */
function validate_phone_number_and_code( $phone_number, $code ) {
    // 从数据库中查询手机号码和验证码是否匹配
    $user_id = get_user_id_by_phone_number_and_code( $phone_number, $code );

    if ( ! $user_id ) {
        return new WP_Error( 'invalid_phone_number_or_code', __( 'Invalid phone number or verification code.', 'custom-authentication' ) );
    }

    $user = get_user_by( 'id', $user_id );

    if ( ! $user ) {
        return new WP_Error( 'invalid_user', __( 'Invalid user.', 'custom-authentication' ) );
    }

    return $user;
}

/**
 * Get user ID by phone number and verification code.
 *
 * @param string $phone_number Phone number.
 * @param string $code         Verification code.
 * @return int|false User ID or false if not found.
 */
function get_user_id_by_phone_number_and_code( $phone_number, $code ) {
    global $wpdb;

    $table_name = $wpdb->prefix . 'phone_verification'; // 存储手机验证码的表名

    $sql = $wpdb->prepare(
        "SELECT user_id FROM {$table_name} WHERE phone_number = %s AND code = %s AND expiration_time > %s",
        $phone_number,
        $code,
        current_time( 'mysql' )
    );

    $user_id = $wpdb->get_var( $sql );

    return $user_id;
}

在这个例子中，我们覆盖了 wp_authenticate() 函数，使用 validate_phone_number_and_code() 函数来验证手机号码和验证码。 如果验证通过，就返回对应的用户对象；如果验证失败，就返回一个 WP_Error 对象。

总结

pluggable.php 是 WordPress 提供的一种非常强大的机制，允许开发者修改 WordPress 的核心功能。 但是，在使用它的时候，一定要谨慎，避免出现冲突和安全问题。 只有在充分理解其原理和注意事项的情况下，才能充分利用 pluggable.php 的优点，为 WordPress 带来更多的可能性。

希望今天的讲座能够帮助大家更好地理解 pluggable.php，并在实际开发中更加得心应手。 谢谢大家！

如果大家有什么问题，欢迎提问。我会尽力解答。