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

各位观众老爷，大家好！我是今天的主讲人，外号“代码搬运工”。今天咱们要聊聊 WordPress 登录的幕后英雄——wp_authenticate() 函数，以及如何利用 authenticate 钩子，打造属于你自己的个性化登录流程。

准备好了吗？咱们这就发车！

一、wp_authenticate()：登录流程的总指挥

wp_authenticate() 函数是 WordPress 登录验证的核心函数，位于 wp-includes/pluggable.php 文件中。它负责接收用户名和密码，然后进行一系列验证，最终决定是否允许用户登录。

简单来说，你可以把它想象成一个机场的安检总指挥，负责检查所有旅客的身份，决定他们能否登机。

1. 函数签名：

function wp_authenticate( $username, $password ) {
    // 函数主体
}

看到了吧，它接收两个参数：$username（用户名）和 $password（密码）。

2. 核心流程概览：

wp_authenticate() 的核心流程大致如下：

初步检查： 检查用户名和密码是否为空。如果为空，直接返回错误。
authenticate 钩子： 这是我们今天的主角！它允许你插入自定义的验证逻辑。
内置验证： WordPress 会进行一些默认的验证，比如检查用户是否存在、密码是否正确等等。
后续处理： 如果验证成功，会设置登录 Cookie，更新用户会话等等。

二、authenticate 钩子：登录流程的变形金刚

authenticate 钩子是 wp_authenticate() 函数中最关键的部分，因为它允许你完全掌控登录验证的流程。你可以利用它：

添加额外的验证步骤 (例如：双因素认证)
修改默认的验证逻辑 (例如：使用 LDAP 服务器验证)
阻止某些用户登录 (例如：基于 IP 地址)
完全替换 WordPress 的登录系统 (例如：使用 OAuth 验证)

1. 钩子位置：

在 wp_authenticate() 函数中，authenticate 钩子位于以下位置：

function wp_authenticate( $username, $password ) {
    // ... (一些初步检查)

    $user = apply_filters( 'authenticate', null, $username, $password );

    // ... (后续的内置验证和处理)
}

看到了吗？ apply_filters('authenticate', null, $username, $password) 这一行代码就是关键。它会调用所有绑定到 authenticate 钩子的函数。

2. 钩子参数：

authenticate 钩子接收三个参数：

$user: (WP_User|WP_Error|null) 初始值为 null。你的钩子函数应该返回一个 WP_User 对象 (如果验证成功), 一个 WP_Error 对象 (如果验证失败), 或者 null (如果你的钩子函数不负责处理此登录请求)。
$username: (string) 用户名。
$password: (string) 密码。

3. 钩子函数的返回值：

WP_User 对象： 表示验证成功，并且返回该用户的 WP_User 对象。WordPress 会接管后续的处理，比如设置登录 Cookie。
WP_Error 对象： 表示验证失败，并且返回一个包含错误信息的 WP_Error 对象。WordPress 会显示错误信息给用户。
null： 表示你的钩子函数不负责处理此登录请求。WordPress 会继续执行后续的验证步骤。

4. 钩子函数执行顺序：

所有绑定到 authenticate 钩子的函数会按照优先级顺序依次执行。优先级越小的函数，越先执行。

三、实战演练：打造自定义登录逻辑

现在，咱们来通过几个实际的例子，看看如何利用 authenticate 钩子，打造各种各样的自定义登录逻辑。

例子 1：添加简单的验证步骤

假设我们要添加一个额外的验证步骤：检查用户名是否包含 "admin" 字符串。如果包含，则阻止用户登录。

add_filter( 'authenticate', 'my_custom_authentication', 30, 3 ); // 优先级 30

function my_custom_authentication( $user, $username, $password ) {
    if ( strpos( $username, 'admin' ) !== false ) {
        $error = new WP_Error( 'admin_username', __( '用户名不能包含 "admin"。' ) );
        return $error; // 验证失败，返回 WP_Error 对象
    }

    return $user; // 验证通过，返回 null (让 WordPress 继续验证)
}

这段代码做了什么？

add_filter( 'authenticate', 'my_custom_authentication', 30, 3 );：将 my_custom_authentication 函数绑定到 authenticate 钩子，优先级为 30。
my_custom_authentication( $user, $username, $password )：钩子函数，接收三个参数。
strpos( $username, 'admin' ) !== false：检查用户名是否包含 "admin" 字符串。
new WP_Error( 'admin_username', __( '用户名不能包含 "admin"。' ) )：如果包含，则创建一个 WP_Error 对象，表示验证失败。
return $error;：返回 WP_Error 对象，阻止用户登录。
return $user;：如果不包含 "admin" 字符串，则返回 $user (也就是 null )，让 WordPress 继续执行后续的验证。

例子 2：使用自定义数据库验证

假设我们有一个自定义的数据库表，其中存储了用户的用户名和密码。我们要使用这个数据库表来验证用户登录。

add_filter( 'authenticate', 'my_custom_db_authentication', 20, 3 );

function my_custom_db_authentication( $user, $username, $password ) {
    global $wpdb;

    // 1. 查询自定义数据库表
    $table_name = $wpdb->prefix . 'my_users'; // 假设表名为 wp_my_users
    $sql = $wpdb->prepare(
        "SELECT * FROM $table_name WHERE username = %s",
        $username
    );
    $user_data = $wpdb->get_row( $sql );

    // 2. 验证用户是否存在
    if ( ! $user_data ) {
        return new WP_Error( 'invalid_username', __( '用户名不存在。' ) );
    }

    // 3. 验证密码
    if ( ! password_verify( $password, $user_data->password ) ) { // 使用 password_verify() 函数验证哈希密码
        return new WP_Error( 'incorrect_password', __( '密码不正确。' ) );
    }

    // 4. 获取 WordPress 用户对象 (如果用户存在于 WordPress 中)
    $wp_user = get_user_by( 'login', $username );
    if ( ! $wp_user ) {
        // 如果用户不存在于 WordPress 中，可以创建一个新的用户
        // 注意：这里需要进行额外的安全检查，确保只有授权的用户才能被创建
        $user_id = wp_insert_user( array(
            'user_login' => $username,
            'user_pass'  => wp_generate_password( 12, false ), // 设置一个随机密码，因为我们不使用 WordPress 的密码系统
            'user_email' => '', // 可选：设置用户邮箱
            'role'       => 'subscriber', // 可选：设置用户角色
        ) );

        if ( is_wp_error( $user_id ) ) {
            return $user_id; // 返回错误
        }

        $wp_user = get_user_by( 'id', $user_id );
    }

    // 5. 验证成功，返回 WP_User 对象
    return $wp_user;
}

这段代码复杂了一点，但它展示了如何完全接管登录验证流程：

查询自定义数据库： 使用 $wpdb 对象查询自定义数据库表，获取用户信息。
验证用户是否存在： 如果用户不存在，返回 WP_Error 对象。
验证密码： 使用 password_verify() 函数验证密码 (假设密码已经哈希存储)。
获取/创建 WordPress 用户对象： 如果用户验证成功，尝试获取 WordPress 用户对象。如果用户不存在于 WordPress 中，可以创建一个新的用户。注意：创建新用户需要进行额外的安全检查，防止恶意用户注册。
返回 WP_User 对象： 如果一切顺利，返回 WP_User 对象，表示验证成功。

例子 3：实现双因素认证

这部分代码只是概念演示，实际的双因素认证方案需要更多的安全措施。

add_filter( 'authenticate', 'my_two_factor_authentication', 10, 3 );

function my_two_factor_authentication( $user, $username, $password ) {
    // 1. 首先进行标准的用户名/密码验证
    $wp_user = get_user_by( 'login', $username );
    if ( ! $wp_user || ! wp_check_password( $password, $wp_user->data->user_pass, $wp_user->ID ) ) {
        return null; // 标准验证失败，让 WordPress 处理错误信息
    }

    // 2. 检查用户是否启用了双因素认证
    $two_factor_enabled = get_user_meta( $wp_user->ID, 'two_factor_enabled', true );
    if ( ! $two_factor_enabled ) {
        return $wp_user; // 用户未启用双因素认证，直接返回 WP_User 对象
    }

    // 3. 检查用户是否已经输入了验证码
    if ( ! isset( $_POST['two_factor_code'] ) || empty( $_POST['two_factor_code'] ) ) {
        // 用户未输入验证码，显示一个表单，要求用户输入验证码
        add_action( 'login_form', 'my_two_factor_form' );
        return new WP_Error( 'two_factor_required', __( '请输入验证码。' ) );
    }

    // 4. 验证验证码
    $two_factor_code = sanitize_text_field( $_POST['two_factor_code'] );
    $stored_code = get_user_meta( $wp_user->ID, 'two_factor_code', true ); // 从用户元数据中获取存储的验证码
    $code_expiration = get_user_meta( $wp_user->ID, 'two_factor_code_expiration', true ); // 获取验证码过期时间

    if ( ! $stored_code || ! hash_equals( $stored_code, hash( 'sha256', $two_factor_code ) ) || time() > $code_expiration ) {
        // 验证码不正确或已过期
        add_action( 'login_form', 'my_two_factor_form' );
        return new WP_Error( 'invalid_two_factor_code', __( '验证码不正确或已过期。' ) );
    }

    // 5. 验证码正确，返回 WP_User 对象
    return $wp_user;
}

function my_two_factor_form() {
    echo '<p><label for="two_factor_code">验证码:<br />
        <input type="text" name="two_factor_code" id="two_factor_code" class="input" size="20" /></label></p>';
}

这段代码实现了双因素认证的基本框架：

标准验证： 首先进行标准的用户名/密码验证。
检查是否启用双因素认证： 检查用户是否启用了双因素认证 (通过用户元数据存储)。
显示验证码表单： 如果用户启用了双因素认证，但未输入验证码，则显示一个表单，要求用户输入验证码。
验证验证码： 验证用户输入的验证码是否正确。
返回 WP_User 对象： 如果一切顺利，返回 WP_User 对象。

重要提示： 这个例子只是一个简单的演示，实际的双因素认证方案需要更复杂的逻辑，包括：

生成和存储验证码 (可以使用 TOTP 算法)
发送验证码给用户 (可以通过短信或邮件)
处理验证码过期
防止暴力破解

四、一些需要注意的坑

在使用 authenticate 钩子时，有一些坑需要注意：

优先级： 钩子函数的优先级很重要。如果你想在 WordPress 的默认验证之前执行你的自定义逻辑，你需要设置一个较低的优先级 (例如：10)。如果你想在默认验证之后执行，你需要设置一个较高的优先级 (例如：30)。
返回值： 确保你的钩子函数返回正确的类型 ( WP_User、WP_Error 或 null )。错误的返回值会导致登录流程出现问题。
安全性： 自定义登录逻辑需要非常注意安全性。你需要防止 SQL 注入、跨站脚本攻击 (XSS) 等常见的安全漏洞。
兼容性： 你的自定义登录逻辑需要与 WordPress 的其他插件和主题兼容。

五、wp_authenticate() 函数的源代码片段

为了更深入地了解 wp_authenticate() 函数，咱们来剖析一下它的源代码片段 (简化版)：

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

    if ( empty( $username ) || empty( $password ) ) {
        $errors = new WP_Error();

        if ( empty( $username ) ) {
            $errors->add( 'required_username', __( '请输入用户名。' ) );
        }

        if ( empty( $password ) ) {
            $errors->add( 'required_password', __( '请输入密码。' ) );
        }

        return $errors;
    }

    /**
     * Filters the user object after the user is authenticated.
     *
     * @since 2.5.0
     *
     * @param WP_User|WP_Error|null $user     WP_User if the user is authenticated, WP_Error otherwise.
     * @param string                $username User's username.
     * @param string                $password User's password.
     */
    $user = apply_filters( 'authenticate', null, $username, $password );

    if ( $user instanceof WP_User ) {
        // 验证成功
        return $user;
    }

    if ( $user instanceof WP_Error ) {
        // 验证失败
        return $user;
    }

    // WordPress 内置验证
    if ( empty( $username ) ) {
        return new WP_Error( 'empty_username', __( '用户名不能为空。' ) );
    }

    if ( strpos( $username, '@' ) ) {
        $user_data = get_user_by( 'email', trim( $username ) );
        if ( empty( $user_data ) ) {
            return new WP_Error( 'invalid_email', __( '邮箱地址不存在。' ) );
        }

        $username = $user_data->user_login;
    }

    $user = get_user_by( 'login', $username );

    if ( ! $user ) {
        return new WP_Error( 'invalid_username', __( '用户名不存在。' ) );
    }

    /**
     * Fires before the password is checked.
     *
     * @since 3.5.0
     *
     * @param WP_User $user User object.
     */
    do_action( 'wp_authenticate_user', $user );

    if ( ! wp_check_password( $password, $user->data->user_pass, $user->ID ) ) {
        /**
         * Fires after a user failed to authenticate.
         *
         * @since 4.3.0
         *
         * @param string $username User's username.
         * @param WP_User $user WP_User object for the user.
         */
        do_action( 'wp_login_failed', $username, $user );

        return new WP_Error( 'incorrect_password', __( '密码不正确。' ) );
    }

    return $user;
}

六、总结

wp_authenticate() 函数是 WordPress 登录验证的核心，而 authenticate 钩子是赋予你掌控权的关键。通过理解 authenticate 钩子的机制，你可以构建各种各样的自定义登录逻辑，满足你的特定需求。记住，安全性是第一位的！

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

附录：常用函数和类

函数/类	描述
`apply_filters()`	应用过滤器钩子。
`add_filter()`	添加过滤器钩子。
`WP_User`	WordPress 用户对象。
`WP_Error`	WordPress 错误对象。
`get_user_by()`	通过用户名、邮箱地址或 ID 获取用户对象。
`wp_check_password()`	验证密码是否与哈希密码匹配。
`wp_insert_user()`	创建一个新的用户。
`sanitize_user()`	清理用户名。
`get_user_meta()`	获取用户元数据。
`update_user_meta()`	更新用户元数据。
`password_verify()`	用于验证哈希密码的函数(PHP >= 5.5)。
`$wpdb`	WordPress 数据库对象。
`do_action()`	执行动作钩子。
`add_action()`	添加动作钩子。
`wp_login_failed`	当用户登录失败时触发的动作钩子。可以用来记录失败的登录尝试或者进行其他的处理。

发表回复 取消回复

发表回复取消回复