剖析 WordPress `WP_Session_Tokens` 类的源码：如何生成、验证和销毁用户会话令牌。

各位观众老爷们，今天咱们来聊聊WordPress的“灵魂伴侣”——会话令牌。别害怕，这玩意儿听起来高大上，实际上就是WordPress用来记住你“是谁”的小纸条，让你不用每次刷新页面都重新登录。今天我们就扒开WP_Session_Tokens类的底裤，看看它是如何生成、验证和销毁这些小纸条的。

你好，我是你们今天的导游，阿帕奇，让我们开始这次愉快的代码之旅吧！

一、会话令牌是个啥？为什么要用它？

想象一下，你走进一家咖啡馆，跟服务员点了一杯咖啡。如果你每次想喝一口咖啡，都得重新告诉服务员：“你好，我要喝一口刚才点的咖啡”，那这咖啡喝起来得多累啊！会话令牌就相当于你拿到了一张写着“我是刚才点咖啡的那位”的卡片，每次你想喝咖啡，只要出示这张卡片，服务员就知道你是谁了。

在WordPress的世界里，会话令牌就是用来识别已登录用户的。如果没有会话令牌，你每次访问一个新页面，WordPress都得重新验证你的用户名和密码，想想都头皮发麻！

二、WP_Session_Tokens类：会话令牌的“幕后黑手”

WP_Session_Tokens类是WordPress负责管理用户会话令牌的核心类。它负责生成、验证、刷新和销毁这些令牌。这个类藏身于wp-includes/class-wp-session-tokens.php文件中。

三、生成会话令牌：制造“我是谁”的小纸条

生成会话令牌的过程主要涉及create()方法。这个方法会创建一系列令牌，并把它们存储在数据库中。

/**
 * Generates a new session token.
 *
 * @since 4.0.0
 *
 * @return string A session token.
 */
public function create() {
    $expiration = time() + $this->get_expiration();
    $token      = wp_generate_password( 43, false, false ); // 生成一个43位的随机字符串
    $this->update( $token, $expiration ); // 更新数据库
    return $token;
}

简单解释一下：

1. $expiration = time() + $this->get_expiration();: 确定令牌的过期时间。get_expiration()方法会根据用户设置和站点配置来决定令牌的有效期。
2. $token = wp_generate_password( 43, false, false );: 生成一个43位的随机字符串作为令牌。wp_generate_password()函数是WordPress提供的生成随机密码的工具，这里我们用它来生成令牌。
3. $this->update( $token, $expiration );: 将令牌和过期时间存储到数据库中。update()方法负责将令牌信息写入用户元数据(wp_usermeta表)中。

update()方法内部的乾坤：

update() 方法是WP_Session_Tokens类中最复杂的方法之一，它负责将新的会话令牌和过期时间存储到用户的元数据中，并清理过期的令牌。

/**
 * Updates a session token.
 *
 * @since 4.0.0
 *
 * @param string   $token      Session token to update.
 * @param int      $expiration Unix timestamp of when the token expires.
 * @param null|int $user_id    Optional. User ID. Defaults to the current user.
 */
public function update( $token, $expiration, $user_id = null ) {
    $user_id = $this->get_user_id( $user_id );

    if ( ! $user_id ) {
        return;
    }

    $sessions = $this->get_sessions( $user_id );

    // If we already have this token, update the expiration.
    if ( isset( $sessions[ $token ] ) ) {
        $sessions[ $token ]['expiration'] = $expiration;
    } else {
        $sessions[ $token ] = array(
            'expiration' => $expiration,
            'ua'         => wp_unslash( $_SERVER['HTTP_USER_AGENT'] ), // 记录用户代理
            'ip'         => WP_Session_Tokens::get_ip_address(),     // 记录IP地址
        );
    }

    $this->update_sessions( $user_id, $sessions );

    /**
     * Fires when a user session is updated.
     *
     * @since 5.6.0
     *
     * @param int    $user_id    User ID.
     * @param string $token      Session token.
     * @param int    $expiration Unix timestamp of when the token expires.
     */
    do_action( 'wp_session_tokens_update_session', $user_id, $token, $expiration );
}

这个方法做了以下几件事情：

1. 获取用户ID: 确保我们知道要为哪个用户存储会话信息。
2. 获取现有会话: 从用户元数据中获取该用户的所有现有会话令牌。
3. 更新或添加会话: 如果令牌已经存在，更新其过期时间；否则，创建一个新的会话条目，包括过期时间、用户代理和IP地址。
4. 存储会话信息: 将更新后的会话信息写回用户元数据。

数据库中长什么样？

用户元数据中会存储一个名为session_tokens的键，它的值是一个序列化的数组，包含了用户的所有会话令牌信息。

例如，一个用户的session_tokens可能长这样：

a:2:{
    s:43:"random_token_1";
    a:3:{
        s:10:"expiration";
        i:1678886400; // Unix 时间戳
        s:2:"ua";
        s:117:"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36"; // 用户代理
        s:2:"ip";
        s:12:"127.0.0.1"; // IP地址
    }
    s:43:"random_token_2";
    a:3:{
        s:10:"expiration";
        i:1678886400;
        s:2:"ua";
        s:117:"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36";
        s:2:"ip";
        s:12:"127.0.0.1";
    }
}

四、验证会话令牌：确认“你是你”的身份

验证会话令牌的过程主要涉及verify()方法。这个方法会检查令牌是否有效（未过期，IP地址和用户代理是否匹配）。

/**
 * Verifies a session token.
 *
 * @since 4.0.0
 *
 * @param string   $token   Session token to verify.
 * @param null|int $user_id Optional. User ID. Defaults to the current user.
 * @return bool True if the session is valid. False otherwise.
 */
public function verify( $token, $user_id = null ) {
    $user_id = $this->get_user_id( $user_id );

    if ( ! $user_id ) {
        return false;
    }

    $sessions = $this->get_sessions( $user_id );

    if ( ! isset( $sessions[ $token ] ) ) {
        return false;
    }

    $session = $sessions[ $token ];

    // Check expiration.
    if ( time() > $session['expiration'] ) {
        return false;
    }

    // Check IP address.
    if ( WP_Session_Tokens::get_ip_address() !== $session['ip'] ) {
        return false;
    }

    // Check user agent.
    if ( wp_unslash( $_SERVER['HTTP_USER_AGENT'] ) !== $session['ua'] ) {
        return false;
    }

    /**
     * Filters whether a session token is considered valid.
     *
     * @since 5.6.0
     *
     * @param bool   $is_valid Whether the session token is considered valid.
     * @param int    $user_id  User ID.
     * @param string $token    Session token.
     * @param array  $session  Session data.
     */
    return apply_filters( 'wp_session_tokens_verify_session', true, $user_id, $token, $session );
}

这个方法做了以下几件事情：

1. 获取用户ID: 确保我们知道要验证哪个用户的令牌。
2. 获取现有会话: 从用户元数据中获取该用户的所有现有会话令牌。
3. 检查令牌是否存在: 如果令牌不在会话列表中，则验证失败。
4. 检查过期时间: 如果令牌已过期，则验证失败。
5. 检查IP地址: 如果当前用户的IP地址与令牌存储的IP地址不匹配，则验证失败。（安全性考虑）
6. 检查用户代理: 如果当前用户的用户代理与令牌存储的用户代理不匹配，则验证失败。（安全性考虑）
7. 应用过滤器: 允许其他插件或主题通过wp_session_tokens_verify_session过滤器来修改验证结果。

五、销毁会话令牌：扔掉“我是谁”的小纸条

销毁会话令牌的过程主要涉及destroy()方法。这个方法会从数据库中删除指定的令牌。

/**
 * Destroys a session token.
 *
 * @since 4.0.0
 *
 * @param string   $token   Session token to destroy.
 * @param null|int $user_id Optional. User ID. Defaults to the current user.
 */
public function destroy( $token, $user_id = null ) {
    $user_id = $this->get_user_id( $user_id );

    if ( ! $user_id ) {
        return;
    }

    $sessions = $this->get_sessions( $user_id );

    if ( ! isset( $sessions[ $token ] ) ) {
        return;
    }

    unset( $sessions[ $token ] );

    $this->update_sessions( $user_id, $sessions );

    /**
     * Fires when a user session is destroyed.
     *
     * @since 5.6.0
     *
     * @param int    $user_id User ID.
     * @param string $token   Session token.
     */
    do_action( 'wp_session_tokens_destroy_session', $user_id, $token );
}

这个方法做了以下几件事情：

1. 获取用户ID: 确保我们知道要销毁哪个用户的令牌。
2. 获取现有会话: 从用户元数据中获取该用户的所有现有会话令牌。
3. 检查令牌是否存在: 如果令牌不在会话列表中，则什么也不做。
4. 删除令牌: 从会话列表中删除指定的令牌。
5. 更新数据库: 将更新后的会话列表写回用户元数据。
6. 触发钩子: 触发wp_session_tokens_destroy_session钩子，允许其他插件或主题执行一些清理工作。

六、销毁所有会话令牌：一锅端！

有时候，我们需要销毁用户的所有会话令牌，例如，当用户修改密码时，或者当管理员强制用户注销时。这时，我们可以使用destroy_all()方法。

/**
 * Destroys all session tokens.
 *
 * @since 4.0.0
 *
 * @param null|int $user_id Optional. User ID. Defaults to the current user.
 */
public function destroy_all( $user_id = null ) {
    $user_id = $this->get_user_id( $user_id );

    if ( ! $user_id ) {
        return;
    }

    delete_user_meta( $user_id, 'session_tokens' );

    /**
     * Fires when all user sessions are destroyed.
     *
     * @since 5.6.0
     *
     * @param int $user_id User ID.
     */
    do_action( 'wp_session_tokens_destroy_all_sessions', $user_id );
}

这个方法非常简单粗暴：直接从用户元数据中删除session_tokens键，从而销毁用户的所有会话令牌。

七、刷新会话令牌：续命大法

会话令牌是有有效期的，一旦过期，用户就需要重新登录。为了避免频繁的重新登录，我们可以定期刷新会话令牌，延长其有效期。

WP_Session_Tokens类并没有提供直接刷新令牌的方法，但是我们可以通过update()方法来更新令牌的过期时间，从而达到刷新的目的。

例如：

$token = $_COOKIE[LOGGED_IN_COOKIE]; // 从cookie中获取token
$expiration = time() + DAY_IN_SECONDS; // 设置新的过期时间（一天后）
$session_tokens = WP_Session_Tokens::get_instance( get_current_user_id() );
$session_tokens->update( $token, $expiration ); // 更新令牌的过期时间

八、WP_Session_Tokens类的其他重要方法

除了上面介绍的方法之外，WP_Session_Tokens类还有一些其他重要的方法，例如：

• get_sessions(): 从用户元数据中获取用户的会话令牌列表。
• update_sessions(): 将用户的会话令牌列表更新到用户元数据中。
• get_expiration(): 获取会话令牌的默认过期时间。
• get_user_id(): 获取当前用户的ID。
• get_instance(): 获取WP_Session_Tokens类的单例实例。
• get_ip_address(): 获取用户的IP地址，考虑到各种代理情况。

九、安全性考量

• IP地址和用户代理验证: verify()方法中对IP地址和用户代理的验证可以防止会话劫持。但是，如果用户的IP地址或用户代理发生变化，会导致验证失败，用户需要重新登录。
• HTTPS: 建议在生产环境中使用HTTPS，以防止会话令牌被窃听。
• 令牌过期时间: 合理设置令牌的过期时间，可以在安全性和用户体验之间取得平衡。
• 防止跨站脚本攻击（XSS）: 在存储和显示会话令牌时，要注意防止XSS攻击。
• Token存储：将Token存储在HTTP Only的Cookie中，防止客户端脚本访问，提高安全性。

十、总结：会话令牌的“一生”

阶段	方法	作用
创建	create()	生成一个新的会话令牌，并将其存储到数据库中。
存储	update()	将会话令牌和过期时间存储到用户的元数据中。
验证	verify()	验证会话令牌是否有效（未过期，IP地址和用户代理是否匹配）。
刷新	update() （更新过期时间）	通过更新会话令牌的过期时间来延长其有效期。
销毁	destroy()	从数据库中删除指定的会话令牌。
销毁所有	destroy_all()	从数据库中删除用户的所有会话令牌。

十一、示例代码：手动创建和验证会话令牌

虽然WordPress会自动处理会话令牌的生成和验证，但是了解如何手动操作可以帮助你更好地理解其工作原理。

// 创建会话令牌
$user_id = get_current_user_id();
$session_tokens = WP_Session_Tokens::get_instance( $user_id );
$token = $session_tokens->create();

// 将令牌存储到Cookie中 (注意：这只是一个示例，实际使用中需要考虑安全问题)
setcookie( 'my_custom_token', $token, time() + DAY_IN_SECONDS, COOKIEPATH, COOKIE_DOMAIN, is_ssl() );

// 验证会话令牌
if ( isset( $_COOKIE['my_custom_token'] ) ) {
    $token = $_COOKIE['my_custom_token'];
    $session_tokens = WP_Session_Tokens::get_instance( $user_id );
    if ( $session_tokens->verify( $token ) ) {
        echo '会话令牌有效！';
    } else {
        echo '会话令牌无效！';
    }
} else {
    echo '没有找到会话令牌！';
}

十二、总结

WP_Session_Tokens类是WordPress用户会话管理的核心，理解它的工作原理对于开发安全可靠的WordPress插件和主题至关重要。 通过学习本文，你应该对会话令牌的生成、验证和销毁过程有了更深入的了解。希望今天的讲座能帮助你更好地理解WordPress的 “灵魂伴侣” – 会话令牌。

本次讲座到此结束，感谢各位的观看，下次再见！