Class yii\web\User

继承yii\web\User » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/web/User.php

User 是用于管理用户身份验证状态的user应用程序组件的类.

你可以使用 $isGuest 判断当前用户是否为来宾. 如果用户是来宾, $identity 属性将返回null. 否则, 它将是 yii\web\IdentityInterface 的一个实例.

你可以调用各种方法来更改用户身份验证状态:

  • login(): 设置指定的身份并记住 session 和 cookie 中的身份验证状态;
  • logout(): 将用户标记为来宾并清除 session 和 cookie 中的相关信息;
  • setIdentity(): 更改用户身份而不触及 session 或 cookie(最好在无状态的 RESTful API 实现中使用)

Note: User 只维护用户身份验证状态. 它不处理如何认证用户. 如何认证用户的逻辑应该在实现 yii\web\IdentityInterface 的类中完成. 你还需要使用此类的名称设置 $identityClass.

默认情况下, User 在 yii\web\Application 中配置为应用程序组件. 你可以通过Yii::$app->user访问该实例.

你可以通过将数组添加到components下的应用程序配置中来修改其配置, 如以下示例所示:

'user' => [
    'identityClass' => 'app\models\User', // User 必须实现 IdentityInterface
    'enableAutoLogin' => true,
    // 'loginUrl' => ['user/login'],
    // ...
]

公共属性

隐藏继承的属性

属性类型描述定义在
$absoluteAuthTimeout integer 无论是否活动, 用户将自动注销的秒数. yii\web\User
$absoluteAuthTimeoutParam string 用于存储已认证状态的绝对过期时间戳值的会话(session)变量名称. yii\web\User
$acceptableRedirectTypes array 此组件应该重定向到 $loginUrl 的 MIME 类型. yii\web\User
$accessChecker yii\rbac\CheckAccessInterface|string|array 用于检查访问权限的访问检查程序对象或访问检查程序的应用程序组件ID. yii\web\User
$authTimeout integer 如果用户保持不活动状态, 将自动注销的秒数. yii\web\User
$authTimeoutParam string 用于存储已认证状态的过期时间戳值的会话(session)变量名称. yii\web\User
$autoRenewCookie boolean 是否在每次请求页面时自动更新身份 cookie. yii\web\User
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. 该属性是只读的. yii\base\Component
$enableAutoLogin boolean 是否启用基于 cookie 的登录. yii\web\User
$enableSession boolean 是否使用会话(session)在多个请求之间保持身份验证状态. yii\web\User
$id string|integer 用户的唯一标识符. 如果为null, 则意味着用户是来宾. 该属性是只读的. yii\web\User
$idParam string 用于存储 $id 值的会话(session)变量名称. yii\web\User
$identity yii\web\IdentityInterface|null 与当前登录的用户关联的身份对象. 如果用户未登录(未经身份验证), 则返回null. yii\web\User
$identityClass string $identity 对象的类名称. yii\web\User
$identityCookie array 身份 cookie 的配置. yii\web\User
$isGuest boolean 当前用户是否是来宾. 该属性是只读的. yii\web\User
$loginUrl string|array 调用 loginRequired() 时用于登录的 URL. yii\web\User
$returnUrl string 登录后用户应重定向到的 URL. 请注意, 该属性的类型在 getter 和 setter 中有所不同. 有关详细信息, 请参阅 getReturnUrl()setReturnUrl(). yii\web\User
$returnUrlParam string 用于存储 $returnUrl 的值的会话(session)变量名称. yii\web\User

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的指定的方法. yii\base\Component
__clone() 在通过克隆现有对象创建对象之后调用此方法. yii\base\Component
__construct() 构造函数. yii\base\BaseObject
__get() 返回组件属性的值. yii\base\Component
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\Component
__set() 设置组件属性的值. yii\base\Component
__unset() 将组件属性设置为null. yii\base\Component
attachBehavior() 将行为附加到此组件. yii\base\Component
attachBehaviors() 将行为列表附加到组件. yii\base\Component
behaviors() 返回此组件应该具有的行为列表. yii\base\Component
can() 检查用户是否可以执行给定权限指定的操作. yii\web\User
canGetProperty() 返回一个值, 指示属性是否可读取. yii\base\Component
canSetProperty() 返回一个值, 指示属性是否可设置. yii\base\Component
className() 返回此类的完全限定名称. yii\base\BaseObject
detachBehavior() 从组件中分离一个行为. yii\base\Component
detachBehaviors() 分离组件中的所有行为. yii\base\Component
ensureBehaviors() 确保在 behaviors() 中声明的行为已附加到此组件. yii\base\Component
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
getId() 返回代表用户的唯一值. yii\web\User
getIdentity() 返回与当前登录用户关联的身份对象. yii\web\User
getIsGuest() 返回一个值, 该值指示用户是否为来宾(未经身份验证). yii\web\User
getReturnUrl() 返回成功登录后浏览器应重定向到的 URL. yii\web\User
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\Component
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\Component
init() 初始化应用程序组件. yii\web\User
login() 登录用户. yii\web\User
loginByAccessToken() 通过给定的访问令牌登录用户. yii\web\User
loginRequired() 将用户浏览器重定向到登录页面. yii\web\User
logout() 注销当前用户. yii\web\User
off() 从该组件分离现有的事件处理程序. yii\base\Component
on() 将事件处理程序附加到事件. yii\base\Component
setIdentity() 设置用户身份对象. yii\web\User
setReturnUrl() 记住 session 中的 URL, 以便稍后可以通过 getReturnUrl() 取回. yii\web\User
switchIdentity() 切换到当前用户的新标识. yii\web\User
trigger() 触发事件. yii\base\Component

受保护的方法

隐藏继承的方法

方法描述定义在
afterLogin() 用户成功登录后, 将调用此方法. yii\web\User
afterLogout() 通过 logout() 注销用户之后立即调用此方法. yii\web\User
beforeLogin() 在成功用户之前, 将调用此方法. yii\web\User
beforeLogout() 通过 logout() 注销用户时, 将调用此方法. yii\web\User
checkRedirectAcceptable() 检查Accept标头是否包含允许重定向到登录页面的内容类型. yii\web\User
getAccessChecker() 返回用于检查访问的访问检查程序. yii\web\User
getAuthManager() 返回与用户组件关联的身份验证管理器. yii\web\User
getIdentityAndDurationFromCookie() 确定身份 cookie 是否具有有效的格式并包含有效的身份验证密钥. yii\web\User
loginByCookie() 通过 cookie 登录用户. yii\web\User
regenerateCsrfToken() 再生 CSRF token. yii\web\User
removeIdentityCookie() 删除身份 cookie. yii\web\User
renewAuthStatus() 使用来自 session 和 cookie 的信息更新身份验证状态. yii\web\User
renewIdentityCookie() 更新身份 cookie. yii\web\User
sendIdentityCookie() 发送身份 cookie. yii\web\User

常量

隐藏继承的常量

常量描述定义在
EVENT_AFTER_LOGIN 'afterLogin' yii\web\User
EVENT_AFTER_LOGOUT 'afterLogout' yii\web\User
EVENT_BEFORE_LOGIN 'beforeLogin' yii\web\User
EVENT_BEFORE_LOGOUT 'beforeLogout' yii\web\User

属性详情

$absoluteAuthTimeout public 属性

无论是否活动, 用户将自动注销的秒数.

Note: 如果 $enableAutoLogintrue, 这将不起作用.

$absoluteAuthTimeoutParam public 属性

用于存储已认证状态的绝对过期时间戳值的会话(session)变量名称. 设置 $absoluteAuthTimeout 时使用.

public string $absoluteAuthTimeoutParam '__absoluteExpire'
$acceptableRedirectTypes public 属性 (可用自版本: 2.0.8)

此组件应该重定向到 $loginUrl 的 MIME 类型.

public array $acceptableRedirectTypes = ['text/html''application/xhtml+xml']
$accessChecker public 属性 (可用自版本: 2.0.9)

用于检查访问权限的访问检查程序对象或访问检查程序的应用程序组件ID. 如果未设置, 将使用应用程序验证管理器.

$authTimeout public 属性

如果用户保持不活动状态, 将自动注销的秒数. 如果未设置该属性, 用户将在当前会话(session)过期后注销(cf. yii\web\Session::$timeout).

Note: 如果 $enableAutoLogintrue, 则此参数无效.

public integer $authTimeout null
$authTimeoutParam public 属性

用于存储已认证状态的过期时间戳值的会话(session)变量名称. 设置 $authTimeout 时使用.

public string $authTimeoutParam '__expire'
$autoRenewCookie public 属性

是否在每次请求页面时自动更新身份 cookie. 仅在 $enableAutoLogintrue时, 此属性才有效. 如果为false, 身份 cookie 将在用户初次登录后的指定持续时间之后过期. 如果为true, 身份 cookie 将在用户上次访问该站点之后的指定持续时间之后过期.

参见 $enableAutoLogin.

public boolean $autoRenewCookie true
$enableAutoLogin public 属性

是否启用基于 cookie 的登录. 默认为false.

Note: 如果 $enableSessionfalse, 则将忽略此属性.

public boolean $enableAutoLogin false
$enableSession public 属性

是否使用会话(session)在多个请求之间保持身份验证状态. 如果你的应用程序是无状态的, 则将此属性设置为false, 这通常是 RESTful API 的例子.

public boolean $enableSession true
$id public 属性

用户的唯一标识符. 如果为null, 则意味着用户是来宾. 该属性是只读的.

public string|integer $id null
$idParam public 属性

用于存储 $id 值的会话(session)变量名称.

public string $idParam '__id'
$identity public 属性

与当前登录的用户关联的身份对象. 如果用户未登录(未经身份验证), 则返回null.

$identityClass public 属性

$identity 对象的类名称.

public string $identityClass null
$identityCookie public 属性

身份 cookie 的配置. 仅在 $enableAutoLogintrue时, 才使用此属性.

参见 yii\web\Cookie.

public array $identityCookie = ['name' => '_identity''httpOnly' => true]
$isGuest public 属性

当前用户是否是来宾. 该属性是只读的.

public boolean $isGuest null
$loginUrl public 属性

调用 loginRequired() 时用于登录的 URL. 如果给定一个数组, 则将调用 yii\web\UrlManager::createUrl() 来创建相应的 URL. 数组的第一个元素应该是登录操作的路由, 其余的 name-value 对是用于构造登录 URL 的 GET 参数. 例如:

['site/login', 'ref' => 1]

如果此属性为null, 则在调用 loginRequired() 时会引发 HTTP 403异常.

public string|array $loginUrl = ['site/login']
$returnUrl public 属性

登录后用户应重定向到的 URL. 请注意, 该属性的类型在 getter 和 setter 中有所不同. 有关详细信息, 请参阅 getReturnUrl()setReturnUrl().

public string $returnUrl null
$returnUrlParam public 属性

用于存储 $returnUrl 的值的会话(session)变量名称.

public string $returnUrlParam '__returnUrl'

方法详情

afterLogin() protected 方法

用户成功登录后, 将调用此方法.

默认实现将触发 EVENT_AFTER_LOGIN 事件. 如果重写此方法, 请确保调用父实现, 以便触发事件.

protected void afterLogin ( $identity, $cookieBased, $duration )
$identity yii\web\IdentityInterface

用户身份信息.

$cookieBased boolean

登录是否是基于 cookie 的.

$duration integer

用户可以保持登录状态的秒数. 如果为0, 则表示登录直到用户关闭浏览器或 session 被手动销毁.

afterLogout() protected 方法

通过 logout() 注销用户之后立即调用此方法.

默认实现将触发 EVENT_AFTER_LOGOUT 事件. 如果重写此方法, 请确保调用父实现, 以便触发事件.

protected void afterLogout ( $identity )
$identity yii\web\IdentityInterface

用户身份信息.

beforeLogin() protected 方法

在成功用户之前, 将调用此方法.

默认实现将触发 EVENT_BEFORE_LOGIN 事件. 如果重写此方法, 请确保调用父实现, 以便触发事件.

protected boolean beforeLogin ( $identity, $cookieBased, $duration )
$identity yii\web\IdentityInterface

用户身份信息.

$cookieBased boolean

登录是否是基于 cookie 的.

$duration integer

用户可以保持登录状态的秒数. 如果为0, 则表示登录直到用户关闭浏览器或 session 被手动销毁.

return boolean

用户是否应该继续登录.

beforeLogout() protected 方法

通过 logout() 注销用户时, 将调用此方法.

默认实现将触发 EVENT_BEFORE_LOGOUT 事件. 如果重写此方法, 请确保调用父实现, 以便触发事件.

protected boolean beforeLogout ( $identity )
$identity yii\web\IdentityInterface

用户身份信息.

return boolean

用户是否应该继续注销.

can() public 方法

检查用户是否可以执行给定权限指定的操作.

Note: 你必须配置authManager应用程序组件才能使用此方法. 否则, 它将始终返回false

public boolean can ( $permissionName, $params = [], $allowCaching true )
$permissionName string

需要访问检查的权限名称(eg. edit post).

$params array

将传递给与分配给用户的角色和权限相关联的规则的 name-value 对.

$allowCaching boolean

是否允许缓存访问检查的结果. 当此参数为true(默认值)时, 如果之前执行过操作的访问检查, 则在调用此方法检查同一操作时将直接返回其结果. 如果此参数为false, 则此方法将始终调用 yii\rbac\CheckAccessInterface::checkAccess() 以获取最新的访问结果.

Note: 此缓存仅在相同的请求中有效, 并且仅在$params = []时才有效.

return boolean

用户是否可以执行给定权限指定的操作.

checkRedirectAcceptable() protected 方法 (可用自版本: 2.0.8)

检查Accept标头是否包含允许重定向到登录页面的内容类型.

默认情况下, 假定登录页面提供text/htmlapplication/xhtml+xml. 你可以通过修改 $acceptableRedirectTypes 属性来更改可接受的内容类型.

参见 $acceptableRedirectTypes.

protected boolean checkRedirectAcceptable ( )
return boolean

该请求是否可以被重定向到登录页面.

getAccessChecker() protected 方法 (可用自版本: 2.0.9)

返回用于检查访问的访问检查程序.

protected yii\rbac\CheckAccessInterface getAccessChecker ( )
getAuthManager() protected 方法 (可用自版本: 2.0.6)
弃用 自版本 2.0.9, 将在 2.1 中删除. 使用 getAccessChecker() 代替.

返回与用户组件关联的身份验证管理器.

默认情况下, 这是authManager应用程序组件. 如果需要, 你可以重写此方法以返回不同的身份验证管理器实例.

protected yii\rbac\ManagerInterface getAuthManager ( )
getId() public 方法

返回代表用户的唯一值.

参见 getIdentity().

public string|integer getId ( )
return string|integer

用户的唯一标识符. 如果为null, 则意味着用户是来宾.

getIdentity() public 方法

返回与当前登录用户关联的身份对象.

$enableSessiontrue时, 此方法可能尝试读取存储在 session 中的用户身份验证数据, 并重建相应的身份对象(如果之前尚未这样做).

参见:

public yii\web\IdentityInterface|null getIdentity ( $autoRenew true )
$autoRenew boolean

是否自动更新认证状态, 如果之前未这样做过. 仅在 $enableSessiontrue时才有用.

return yii\web\IdentityInterface|null

与当前登录的用户关联的身份对象. 如果用户未登录(未经身份验证), 则返回null.

getIdentityAndDurationFromCookie() protected 方法 (可用自版本: 2.0.9)

确定身份 cookie 是否具有有效的格式并包含有效的身份验证密钥.

$enableAutoLogin 为'true'时, 使用此方法. 该方法尝试使用身份 cookie 中的信息对用户进行身份验证.

参见 loginByCookie().

protected array|null getIdentityAndDurationFromCookie ( )
return array|null

如果有效, 则返回identityduration数组, 否则返回null.

getIsGuest() public 方法

返回一个值, 该值指示用户是否为来宾(未经身份验证).

参见 getIdentity().

public boolean getIsGuest ( )
return boolean

当前用户是否是来宾.

getReturnUrl() public 方法

返回成功登录后浏览器应重定向到的 URL.

该方法从 session 中读取返回 URL. 它通常由登录操作使用, 可能会调用此方法将浏览器重定向到成功身份验证后的位置.

参见 loginRequired().

public string getReturnUrl ( $defaultUrl null )
$defaultUrl string|array

如果以前未设置, 则默认的返回 URL. 如果为null, 并且以前未设置返回 URL, 则将重定向到 yii\web\Application::$homeUrl. 请参阅 setReturnUrl(), 以了解可接受的 URL 格式.

return string

登录后用户应重定向到的 URL.

init() public 方法

初始化应用程序组件.

public void init ( )
login() public 方法

登录用户.

登录用户后:

  • 用户的身份信息可以从 $identity 属性获得.

如果 $enableSessiontrue:

  • 身份信息将被存储在 session 中, 并在下一个请求中可用.
  • $duration == 0的情况下: 只要 session 保持活动状态或者直到用户关闭浏览器.
  • $duration > 0的情况下: 只要会话(session)保持活动状态, 或者只要 $enableAutoLogin 设置为true时, cookie 在$duration内保持有效时间即可.

如果 $enableSessionfalse:

  • $duration参数将被忽略.
public boolean login ( yii\web\IdentityInterface $identity, $duration 0 )
$identity yii\web\IdentityInterface

用户身份(应该已经通过身份认证).

$duration integer

用户可以保持登录状态的秒数, 默认为0.

return boolean

用户是否已登录.

loginByAccessToken() public 方法

通过给定的访问令牌登录用户.

该方法将首先通过使用所提供的访问令牌调用 yii\web\IdentityInterface::findIdentityByAccessToken() 来认证用户. 如果成功, 它将调用 login() 登录经过身份验证的用户. 如果认证失败或 login() 不成功, 它将返回null.

public yii\web\IdentityInterface|null loginByAccessToken ( $token, $type null )
$token string

访问令牌.

$type mixed

令牌的类型. 此参数的值取决于实现. 例如, yii\filters\auth\HttpBearerAuth 会将此参数设置为yii\filters\auth\HttpBearerAuth.

return yii\web\IdentityInterface|null

与给定访问令牌关联的身份. 如果访问令牌无效或 login() 不成功, 则返回null.

loginByCookie() protected 方法

通过 cookie 登录用户.

此方法尝试使用 identity cookie 提供的 ID 和 authKey 信息登录用户.

protected void loginByCookie ( )
loginRequired() public 方法

将用户浏览器重定向到登录页面.

在重定向之前, 当前 URL(如果它不是 AJAX url)将被保存为 $returnUrl, 以便用户浏览器可以在成功登录后重定向回当前页面.

请确保设置了 $loginUrl, 以便在调用此方法后, 可以将用户浏览器重定向到指定的登录 URL.

Note: 当设置 $loginUrl 时, 调用此方法将不会终止应用程序的执行.

public yii\web\Response loginRequired ( $checkAjax true, $checkAcceptHeader true )
$checkAjax boolean

检查请求是是否 AJAX 请求. 当为true, 并且请求是一个 AJAX 请求, 则不会将当前的 URL(用于 AJAX 请求)设置为返回的 URL.

$checkAcceptHeader boolean

检查请求是否接受 HTML 响应. 默认为true. 如果为true, 并且请求不接受 HTML 响应, 则不会将当前 URL 设置为返回 URL. 此外, 不是重定向用户, 而是抛出 ForbiddenHttpException. 该参数自版本2.0.8起可用.

return yii\web\Response

如果设置了 $loginUrl, 则重定向响应.

throws yii\web\ForbiddenHttpException

如果未设置 $loginUrl 或重定向不适用, 则会出现 Access Denied(拒绝访问) HTTP 异常.

logout() public 方法

注销当前用户.

这将删除与身份验证相关的 session 数据. 如果$destroySessiontrue, 则将删除所有 session.

public boolean logout ( $destroySession true )
$destroySession boolean

是否销毁整个 session. 默认为true. 如果 $enableSessionfalse, 则忽略此参数.

return boolean

用户是否注销.

regenerateCsrfToken() protected 方法 (可用自版本: 2.0.14.2)

再生 CSRF token.

protected void regenerateCsrfToken ( )
removeIdentityCookie() protected 方法 (可用自版本: 2.0.9)

删除身份 cookie.

$enableAutoLogintrue时, 使用此方法.

protected void removeIdentityCookie ( )
renewAuthStatus() protected 方法

使用来自 session 和 cookie 的信息更新身份验证状态.

该方法将尝试使用 $idParam session 变量来确定用户身份.

如果设置了 $authTimeout, 则此方法将刷新计时器.

如果无法通过 session 确定用户身份, 则在 $enableAutoLogintrue的情况下, 此方法将尝试 通过 cookie 登录.

protected void renewAuthStatus ( )
renewIdentityCookie() protected 方法

更新身份 cookie.

此方法会将身份 cookie 的到期时间设置为当前时间加上最初指定的 cookie 持续时间.

protected void renewIdentityCookie ( )
sendIdentityCookie() protected 方法

发送身份 cookie.

$enableAutoLogintrue时, 使用此方法. 它在 cookie 中保存 $id, auth key 和基于 cookie 的登录信息的持续时间.

参见 loginByCookie().

protected void sendIdentityCookie ( $identity, $duration )
$identity yii\web\IdentityInterface
$duration integer

用户可以保持登录状态的秒数.

setIdentity() public 方法

设置用户身份对象.

Note: 此方法不处理 session 或 cookie. 你通常应该使用 switchIdentity() 更改当前用户的身份.

public void setIdentity ( $identity )
$identity yii\web\IdentityInterface|null

与当前登录的用户关联的身份对象. 如果为null, 则表示当前用户将是没有任何关联身份的来宾.

throws yii\base\InvalidValueException

如果$identity对象未实现 yii\web\IdentityInterface.

setReturnUrl() public 方法

记住 session 中的 URL, 以便稍后可以通过 getReturnUrl() 取回.

public void setReturnUrl ( $url )
$url string|array

登录后用户应重定向到的 URL. 如果给定一个数组, 则将调用 yii\web\UrlManager::createUrl() 创建相应的 URL. 数组的第一个元素应该是路由, 其余的 name-value 对是用于构造 URL 的 GET 参数. 例如:

['admin/index', 'ref' => 1]
switchIdentity() public 方法

切换到当前用户的新标识.

$enableSessiontrue时, 此方法可以根据$duration的值使用 session 和/或 cookie 来存储用户身份信息. 请参阅 login() 了解更多详情.

当前用户需要与相应的身份信息相关联时, 此方法主要通过 login(), logout()loginByCookie() 调用.

public void switchIdentity ( $identity, $duration 0 )
$identity yii\web\IdentityInterface|null

与当前用户相关联的身份信息. 如果为`null', 则意味着将当前用户切换为来宾.

$duration integer

用户可以保持登录状态的秒数. 仅在$identity不为`null'时使用此参数.