分析 WordPress `wp_authenticate()` 函数的源码：如何通过 `authenticate` 钩子处理自定义登录逻辑。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷们，大家好！今天咱们聊聊WordPress里一个非常重要的函数，也是很多开发者都感兴趣的部分：wp_authenticate()，以及它背后的authenticate钩子。

说白了，wp_authenticate()就是WordPress登录验证的核心，而authenticate钩子则允许我们自定义登录验证的逻辑，让登录过程变得更加灵活和强大。

一、wp_authenticate() 函数：登录验证的门面担当

首先，咱们来看看wp_authenticate()函数的基本结构。这个函数藏在wp-includes/pluggable.php文件中。

function wp_authenticate( $username, $password ) {
    $username = sanitize_user( $username );
    $password = trim( $password );

    /**
     * Filters the user to authenticate.
     *
     * @since 2.8.0
     *
     * @param WP_User|WP_Error|null $user      WP_User if the user is authenticated. WP_Error or null otherwise.
     * @param string                $username  The user's username.
     * @param string                $password  The user's password.
     */
    $user = apply_filters( 'authenticate', null, $username, $password );

    if ( null === $user ) {
        if ( empty( $username ) ) {
            $user = new WP_Error( 'empty_username', __( '<strong>Error</strong>: Username is required.' ) );
        } elseif ( empty( $password ) ) {
            $user = new WP_Error( 'empty_password', __( '<strong>Error</strong>: Password is required.' ) );
        } else {
            $user = get_user_by( 'login', $username );
            if ( isset( $user->user_status ) && 0 < $user->user_status ) {
                $user = new WP_Error( 'account_pending', __( '<strong>Error</strong>: Your account is still pending, please check your email.' ) );
            }
            if ( isset( $user->ID ) ) {
                $user = wp_validate_auth_cookie( '', 'logged_in' );
            }
            if ( ! $user ) {
                $user = wp_check_password( $password, $user->user_pass, $user->ID );
                if ( is_wp_error( $user ) ) {
                    /**
                     * Fires after an authentication error if a user is found.
                     *
                     * @since 3.3.0
                     *
                     * @param WP_Error $user     WP_Error object representing authentication error.
                     * @param string   $username The user's username.
                     */
                    do_action( 'wp_login_failed', $username );
                    return $user;
                }
            }
        }
    }

    /**
     * Filters the authenticated user.
     *
     * @since 2.8.0
     *
     * @param WP_User|WP_Error $user      WP_User if the user is authenticated. WP_Error object otherwise.
     * @param string           $username  The user's username.
     * @param string           $password  The user's password.
     */
    $user = apply_filters( 'wp_authenticate_user', $user, $password );

    if ( is_wp_error( $user ) ) {
        /**
         * Fires after an authentication error.
         *
         * @since 3.0.0
         *
         * @param string $username The user's username.
         */
        do_action( 'wp_login_failed', $username );
    }

    return $user;
}

简单来说，wp_authenticate()函数做了这么几件事：

清理数据： 使用 sanitize_user() 清理用户名，trim() 清理密码两端的空格。
应用 authenticate 钩子： 这是重点！它允许我们插入自定义的验证逻辑。
默认验证逻辑： 如果 authenticate 钩子没有返回用户对象，则进行默认的验证：
- 检查用户名和密码是否为空。
- 通过 get_user_by() 根据用户名获取用户对象。
- 使用 wp_check_password() 验证密码。
应用 wp_authenticate_user 钩子： 对验证后的用户对象进行最后的过滤。
错误处理： 如果验证失败，则触发 wp_login_failed 动作。
返回结果： 返回用户对象（WP_User）或错误对象（WP_Error）。

二、authenticate 钩子：自定义登录验证的入口

authenticate 钩子是wp_authenticate()函数的核心。它允许我们完全掌控登录验证的过程。我们可以用它来实现各种各样的功能，比如：

使用邮箱地址登录。
使用第三方认证系统（例如 OAuth）。
增加额外的安全验证（例如双因素认证）。
阻止特定用户登录。

钩子函数参数：

参数	类型	描述
`$user`	`WP_User`\|`WP_Error`\|`null`	如果之前的钩子函数已经验证了用户，则该参数为用户对象（`WP_User`）。如果之前的钩子函数返回了一个错误，则该参数为错误对象（`WP_Error`）。如果这是第一个执行的钩子函数，则该参数为 `null`。
`$username`	`string`	用户输入的用户名。
`$password`	`string`	用户输入的密码。

返回值：

如果验证成功，则返回一个 WP_User 对象。
如果验证失败，则返回一个 WP_Error 对象。
如果想让 WordPress 继续执行默认的验证逻辑，则返回 null。

简单示例：使用邮箱地址登录

假设我们想让用户可以使用邮箱地址登录。我们可以这样做：

add_filter( 'authenticate', 'my_authenticate_email', 30, 3 );

function my_authenticate_email( $user, $username, $password ) {
    // 避免重复验证。如果已经有用户对象或错误对象，直接返回。
    if ( !empty( $user ) ) {
        return $user;
    }

    // 使用邮箱地址查找用户
    $user = get_user_by( 'email', $username );

    // 如果找到了用户，并且密码正确，则返回用户对象
    if ( $user && wp_check_password( $password, $user->user_pass, $user->ID ) ) {
        return $user;
    }

    // 如果没有找到用户，或者密码不正确，则返回 null，让 WordPress 继续执行默认的验证逻辑
    return null;
}

这段代码做了什么？

注册钩子： 使用 add_filter() 函数将 my_authenticate_email() 函数注册到 authenticate 钩子上。 30 是优先级，3 是参数个数。
检查 $user： 首先检查 $user 是否为空。如果 $user 已经是一个 WP_User 对象或 WP_Error 对象，说明之前的钩子函数已经验证了用户，或者验证失败，直接返回 $user，避免重复验证。
使用邮箱查找用户： 使用 get_user_by( 'email', $username ) 函数根据邮箱地址查找用户。
验证密码： 如果找到了用户，使用 wp_check_password() 函数验证密码。
返回结果： 如果验证成功，返回用户对象；如果验证失败，返回 null。

更完善的示例：双因素认证

现在，咱们来一个更高级的例子：双因素认证。这个例子稍微复杂一些，但能更好地展示 authenticate 钩子的强大之处。

首先，我们需要一个存储用户双因素认证状态的字段。我们可以使用用户元数据（user meta）来实现。

// 添加用户元数据
add_action( 'show_user_profile', 'my_extra_user_profile_fields' );
add_action( 'edit_user_profile', 'my_extra_user_profile_fields' );

function my_extra_user_profile_fields( $user ) { ?>
    <h3><?php _e( '双因素认证', 'your_textdomain' ); ?></h3>

    <table class="form-table">
        <tr>
            <th><label for="two_factor_enabled"><?php _e( '启用双因素认证', 'your_textdomain' ); ?></label></th>
            <td>
                <input type="checkbox" name="two_factor_enabled" id="two_factor_enabled" value="1" <?php checked( get_user_meta( $user->ID, 'two_factor_enabled', true ), 1 ); ?> />
                <span class="description"><?php _e( '启用后，您需要输入验证码才能登录。', 'your_textdomain' ); ?></span>
            </td>
        </tr>
    </table>
<?php }

// 保存用户元数据
add_action( 'personal_options_update', 'my_save_extra_user_profile_fields' );
add_action( 'edit_user_profile_update', 'my_save_extra_user_profile_fields' );

function my_save_extra_user_profile_fields( $user_id ) {
    if ( ! current_user_can( 'edit_user', $user_id ) ) {
        return false;
    }

    update_user_meta( $user_id, 'two_factor_enabled', isset( $_POST['two_factor_enabled'] ) ? 1 : 0 );
}

这段代码会在用户个人资料页面添加一个“启用双因素认证”的复选框，并保存用户的选择。

接下来，我们需要一个函数来生成和验证验证码。这里我们简单地使用一个随机数。在实际项目中，你应该使用更安全的方案，例如 Google Authenticator 或短信验证码。

// 生成验证码（简化版）
function my_generate_two_factor_code( $user_id ) {
    $code = rand( 100000, 999999 ); // 生成一个 6 位数的随机数
    update_user_meta( $user_id, 'two_factor_code', $code );
    update_user_meta( $user_id, 'two_factor_code_expiry', time() + 300 ); // 验证码有效期 5 分钟
    return $code;
}

// 验证验证码
function my_verify_two_factor_code( $user_id, $code ) {
    $stored_code = get_user_meta( $user_id, 'two_factor_code', true );
    $expiry = get_user_meta( $user_id, 'two_factor_code_expiry', true );

    if ( $stored_code == $code && time() <= $expiry ) {
        delete_user_meta( $user_id, 'two_factor_code' ); // 验证成功后删除验证码
        delete_user_meta( $user_id, 'two_factor_code_expiry' );
        return true;
    }

    return false;
}

最后，我们需要修改登录表单，添加一个输入验证码的字段，并在 authenticate 钩子中验证验证码。

// 修改登录表单
add_action( 'login_form', 'my_add_two_factor_field' );

function my_add_two_factor_field() {
    ?>
    <p>
        <label for="two_factor_code"><?php _e( '验证码', 'your_textdomain' ); ?><br />
            <input type="text" name="two_factor_code" id="two_factor_code" class="input" value="" size="20" /></label>
    </p>
    <?php
}

// 验证验证码
add_filter( 'authenticate', 'my_authenticate_two_factor', 20, 3 );

function my_authenticate_two_factor( $user, $username, $password ) {
    // 避免重复验证。如果已经有用户对象或错误对象，直接返回。
    if ( !empty( $user ) ) {
        return $user;
    }

    // 使用用户名查找用户
    $user = get_user_by( 'login', $username );

    // 如果没有找到用户，或者密码不正确，则返回 null，让 WordPress 继续执行默认的验证逻辑
    if ( !$user || !wp_check_password( $password, $user->user_pass, $user->ID ) ) {
        return null;
    }

    // 检查是否启用了双因素认证
    $two_factor_enabled = get_user_meta( $user->ID, 'two_factor_enabled', true );

    if ( $two_factor_enabled ) {
        // 获取用户输入的验证码
        $code = isset( $_POST['two_factor_code'] ) ? $_POST['two_factor_code'] : '';

        // 如果没有输入验证码，则返回一个错误
        if ( empty( $code ) ) {
            return new WP_Error( 'two_factor_code_required', __( '<strong>错误</strong>：请输入验证码。', 'your_textdomain' ) );
        }

        // 验证验证码
        if ( !my_verify_two_factor_code( $user->ID, $code ) ) {
            return new WP_Error( 'two_factor_code_invalid', __( '<strong>错误</strong>：验证码不正确。', 'your_textdomain' ) );
        }
    }

    // 如果一切正常，则返回用户对象
    return $user;
}

// 发送验证码
add_action( 'wp_login', 'my_send_two_factor_code', 10, 2 );

function my_send_two_factor_code( $username, $user ) {
    $two_factor_enabled = get_user_meta( $user->ID, 'two_factor_enabled', true );

    if ( $two_factor_enabled ) {
        $code = my_generate_two_factor_code( $user->ID );
        // 在这里，你可以将验证码发送到用户的邮箱或手机上
        // 这里只是一个示例，实际项目中你需要使用更可靠的发送方式
        echo '<script>alert("您的验证码是：' . $code . '");</script>';
    }
}

这段代码做了很多事情：

修改登录表单： 使用 login_form 动作在登录表单中添加一个“验证码”字段。
验证密码： 首先使用 WordPress 默认的验证逻辑验证用户名和密码。
检查双因素认证状态： 如果用户启用了双因素认证，则检查用户是否输入了验证码。
验证验证码： 使用 my_verify_two_factor_code() 函数验证验证码。
返回结果： 如果验证成功，返回用户对象；如果验证失败，返回错误对象。
发送验证码： 使用 wp_login 动作，在用户成功登录后，发送验证码到用户的邮箱或手机。

三、注意事项

优先级： add_filter() 函数的第三个参数是优先级。优先级越低，钩子函数越先执行。你需要根据你的需求设置合适的优先级。
安全性： 在实际项目中，你需要特别注意安全性。不要使用简单的随机数作为验证码，要使用更安全的方案，例如 Google Authenticator 或短信验证码。同时，要防止暴力破解，例如限制登录尝试次数。
用户体验： 良好的用户体验也很重要。要清晰地告诉用户需要做什么，如果验证失败，要给出明确的错误提示。
测试： 在发布你的代码之前，一定要进行充分的测试。

四、总结

wp_authenticate() 函数和 authenticate 钩子是 WordPress 登录验证的核心。通过使用 authenticate 钩子，我们可以自定义登录验证的逻辑，实现各种各样的功能。但是，在使用 authenticate 钩子时，一定要注意安全性、用户体验和测试。

希望今天的讲座对你有所帮助！下次再见！

发表回复 取消回复

发表回复取消回复