身份验证 ¶

身份验证是验证用户身份的过程。它通常使用标识符（例如用户名或电子邮件地址）和秘密令牌（例如密码或访问令牌）来判断用户是否是他声称的那个人。身份验证是登录功能的基础。

Yii 提供了一个身份验证框架，它将各种组件连接起来以支持登录。要使用此框架，您主要需要执行以下工作

• 配置 user 应用程序组件；
• 创建一个实现 yii\web\IdentityInterface 接口的类。

配置 yii\web\User ¶

user 应用程序组件管理用户身份验证状态。它要求您指定一个 身份类，其中包含实际的身份验证逻辑。在以下应用程序配置中，user 的 身份类 被配置为 app\models\User，其实现将在下一小节中说明。

return [
    'components' => [
        'user' => [
            'identityClass' => 'app\models\User',
        ],
    ],
];

实现 yii\web\IdentityInterface ¶

身份类 必须实现 yii\web\IdentityInterface，其中包含以下方法

• findIdentity()：它使用指定的用户 ID 查找身份类的实例。当您需要通过会话维护登录状态时，将使用此方法。
• findIdentityByAccessToken()：它使用指定的访问令牌查找身份类的实例。当您需要通过单个秘密令牌（例如在无状态 RESTful 应用程序中）对用户进行身份验证时，将使用此方法。
• getId()：它返回此身份实例表示的用户 ID。
• getAuthKey()：它返回一个用于验证会话和自动登录的密钥（如果已启用）。
• validateAuthKey()：它实现了验证身份验证密钥的逻辑。

如果某个特定方法不需要，您可以使用空主体来实现它。例如，如果您的应用程序是一个纯无状态的 RESTful 应用程序，您只需要实现 findIdentityByAccessToken() 和 getId()，而将所有其他方法保留为空主体。或者，如果您的应用程序仅使用会话进行身份验证，则需要实现除 findIdentityByAccessToken() 之外的所有方法。

在以下示例中，一个 身份类 被实现为与 user 数据库表关联的 Active Record 类。

<?php

use yii\db\ActiveRecord;
use yii\web\IdentityInterface;

class User extends ActiveRecord implements IdentityInterface
{
    public static function tableName()
    {
        return 'user';
    }

    /**
     * Finds an identity by the given ID.
     *
     * @param string|int $id the ID to be looked for
     * @return IdentityInterface|null the identity object that matches the given ID.
     */
    public static function findIdentity($id)
    {
        return static::findOne($id);
    }

    /**
     * Finds an identity by the given token.
     *
     * @param string $token the token to be looked for
     * @return IdentityInterface|null the identity object that matches the given token.
     */
    public static function findIdentityByAccessToken($token, $type = null)
    {
        return static::findOne(['access_token' => $token]);
    }

    /**
     * @return int|string current user ID
     */
    public function getId()
    {
        return $this->id;
    }

    /**
     * @return string|null current user auth key
     */
    public function getAuthKey()
    {
        return $this->auth_key;
    }

    /**
     * @param string $authKey
     * @return bool|null if auth key is valid for current user
     */
    public function validateAuthKey($authKey)
    {
        return $this->getAuthKey() === $authKey;
    }
}

您可以使用以下代码为每个用户生成一个身份验证密钥，然后将其存储在 user 表中。

class User extends ActiveRecord implements IdentityInterface
{
    ......

    public function beforeSave($insert)
    {
        if (parent::beforeSave($insert)) {
            if ($this->isNewRecord) {
                $this->auth_key = \Yii::$app->security->generateRandomString();
            }
            return true;
        }
        return false;
    }
}

注意：不要将 User 身份类与 yii\web\User 混淆。前者是实现身份验证逻辑的类。它通常被实现为与某些持久存储关联的 Active Record 类，用于存储用户凭据信息。后者是一个应用程序组件类，负责管理用户身份验证状态。

使用 yii\web\User ¶

您主要通过 user 应用程序组件来使用 yii\web\User。

您可以使用表达式 Yii::$app->user->identity 检测当前用户的身份。它返回一个表示当前登录用户的 身份类 实例，或者如果当前用户未经身份验证（表示访客）则返回 null。以下代码展示了如何从 yii\web\User 中检索其他与身份验证相关的信息。

// the current user identity. `null` if the user is not authenticated.
$identity = Yii::$app->user->identity;

// the ID of the current user. `null` if the user not authenticated.
$id = Yii::$app->user->id;

// whether the current user is a guest (not authenticated)
$isGuest = Yii::$app->user->isGuest;

要登录用户，您可以使用以下代码。

// find a user identity with the specified username.
// note that you may want to check the password if needed
$identity = User::findOne(['username' => $username]);

// logs in the user
Yii::$app->user->login($identity);

yii\web\User::login() 方法将当前用户的身份设置为 yii\web\User。如果会话已 启用，它将保留会话中的身份，以便在整个会话期间维护用户身份验证状态。如果启用了基于 Cookie 的登录（即“记住我”登录），它还将身份保存在 Cookie 中，以便只要 Cookie 保持有效，就可以从 Cookie 中恢复用户身份验证状态。

为了启用基于 Cookie 的登录，您需要在应用程序配置中将 yii\web\User::$enableAutoLogin 配置为 true。在调用 yii\web\User::login() 方法时，您还需要提供一个持续时间参数。

要注销用户，只需调用

Yii::$app->user->logout();

请注意，仅当启用会话时，注销用户才有意义。该方法将从内存和会话中清除用户身份验证状态。默认情况下，它还会销毁所有用户会话数据。如果您想保留会话数据，则应改为调用 Yii::$app->user->logout(false)。

身份验证事件 ¶

yii\web\User 类在登录和注销过程中引发了一些事件。

• EVENT_BEFORE_LOGIN：在 yii\web\User::login() 开始时引发。如果事件处理程序将事件对象的 isValid 属性设置为 false，则登录过程将被取消。
• EVENT_AFTER_LOGIN：在成功登录后引发。
• EVENT_BEFORE_LOGOUT：在 yii\web\User::logout() 开始时引发。如果事件处理程序将事件对象的 isValid 属性设置为 false，则注销过程将被取消。
• EVENT_AFTER_LOGOUT：在成功注销后引发。

您可以响应这些事件来实现诸如登录审计、在线用户统计等功能。例如，在 EVENT_AFTER_LOGIN 的处理程序中，您可以将登录时间和 IP 地址记录在 user 表中。