User

Type
Class
Namespace
craft\web
Inherits
craft\web\User » yii\web\User (opens new window) » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)
Implements
yii\base\Configurable (opens new window)
Since
3.0.0

The User component provides APIs for managing the user authentication status.

An instance of the User component is globally accessible in Craft via Craft::$app->user (opens new window).

View source (opens new window)

# Public Properties

Property Description
absoluteAuthTimeout (opens new window) integer (opens new window) – The number of seconds in which the user will be logged out automatically regardless of activity.
absoluteAuthTimeoutParam (opens new window) string (opens new window) – The session variable name used to store the value of absolute expiration timestamp of the authenticated state.
acceptableRedirectTypes (opens new window) array (opens new window) – MIME types for which this component should redirect to the loginUrl (opens new window).
accessChecker (opens new window) yii\rbac\CheckAccessInterface (opens new window), string (opens new window), array (opens new window) – The access checker object to use for checking access or the application component ID of the access checker.
authTimeout (opens new window) integer (opens new window) – The number of seconds in which the user will be logged out automatically if he remains inactive.
authTimeoutParam (opens new window) string (opens new window) – The session variable name used to store the value of expiration timestamp of the authenticated state.
autoRenewCookie (opens new window) boolean (opens new window) – Whether to automatically renew the identity cookie each time a page is requested.
behaviors (opens new window) yii\base\Behavior (opens new window) – List of behaviors attached to this component
elevatedSessionTimeout integer (opens new window), boolean (opens new window) – The number of seconds left in the current elevated user session or false if it has been disabled.
elevatedSessionTimeoutParam string (opens new window) – The session variable name used to store the value of the expiration timestamp of the elevated session state.
enableAutoLogin (opens new window) boolean (opens new window) – Whether to enable cookie-based login.
enableSession (opens new window) boolean (opens new window) – Whether to use session to persist authentication status across multiple requests.
hasElevatedSession boolean (opens new window) – Whether the user currently has an elevated session
id (opens new window) string (opens new window), integer (opens new window) – The unique identifier for the user.
idParam (opens new window) string (opens new window) – The session variable name used to store the value of id (opens new window).
identity (opens new window) yii\web\IdentityInterface (opens new window), null (opens new window) – The identity object associated with the currently logged-in user.
identityClass (opens new window) string (opens new window) – The class name of the identity (opens new window) object.
identityCookie (opens new window) array (opens new window) – The configuration of the identity cookie.
isAdmin boolean (opens new window) – Whether the current user is an admin.
isGuest boolean (opens new window) – Whether the current user is a guest.
loginUrl (opens new window) string (opens new window), array (opens new window) – The URL for login when loginRequired() (opens new window) is called.
remainingSessionTime integer (opens new window) – The seconds left in the session, or -1 if their session will expire when their HTTP session ends.
rememberedUsername string (opens new window), null (opens new window)
returnUrl string (opens new window) – The URL that the user should be redirected to after login.
returnUrlParam (opens new window) string (opens new window) – The session variable name used to store the value of returnUrl (opens new window).
tokenParam string (opens new window) – The session variable name used to store the user session token.
usernameCookie array (opens new window) – The configuration of the username cookie.

# elevatedSessionTimeout

Type
integer (opens new window), boolean (opens new window)
Default value
null
Access
Read-only

The number of seconds left in the current elevated user session or false if it has been disabled.

View source (opens new window)

# elevatedSessionTimeoutParam

Type
string (opens new window)
Default value
'__elevated_timeout'

The session variable name used to store the value of the expiration timestamp of the elevated session state.

View source (opens new window)

# hasElevatedSession

Type
boolean (opens new window)
Default value
null
Access
Read-only

Whether the user currently has an elevated session

View source (opens new window)

# isAdmin

Type
boolean (opens new window)
Default value
null
Access
Read-only

Whether the current user is an admin.

View source (opens new window)

# isGuest

Type
boolean (opens new window)
Default value
null
Access
Read-only

Whether the current user is a guest.

View source (opens new window)

# remainingSessionTime

Type
integer (opens new window)
Default value
null
Access
Read-only

The seconds left in the session, or -1 if their session will expire when their HTTP session ends.

View source (opens new window)

# rememberedUsername

Type
string (opens new window), null (opens new window)
Default value
null
Access
Read-only

View source (opens new window)

# returnUrl

Type
string (opens new window)
Default value
null

The URL that the user should be redirected to after login.

View source (opens new window)

# tokenParam

Type
string (opens new window)
Default value
'__token'

The session variable name used to store the user session token.

View source (opens new window)

# usernameCookie

Type
array (opens new window)
Default value
null

The configuration of the username cookie.

See also yii\web\Cookie (opens new window)

View source (opens new window)

# Public Methods

Method Description
__call() (opens new window) Calls the named method which is not a class method.
__clone() (opens new window) This method is called after the object is created by cloning an existing one.
__construct() (opens new window) Constructor.
__get() (opens new window) Returns the value of an object property.
__isset() (opens new window) Checks if a property is set, i.e. defined and not null.
__set() (opens new window) Sets value of an object property.
__unset() (opens new window) Sets an object property to null.
attachBehavior() (opens new window) Attaches a behavior to this component.
attachBehaviors() (opens new window) Attaches a list of behaviors to the component.
behaviors() (opens new window) Returns a list of behaviors that this component should behave as.
can() (opens new window) Checks if the user can perform the operation as specified by the given permission.
canGetProperty() (opens new window) Returns a value indicating whether a property can be read.
canSetProperty() (opens new window) Returns a value indicating whether a property can be set.
checkPermission() Returns whether the current user has a given permission.
className() (opens new window) Returns the fully qualified name of this class.
destroyDebugPreferencesInSession() Removes the debug preferences from the session.
detachBehavior() (opens new window) Detaches a behavior from the component.
detachBehaviors() (opens new window) Detaches all behaviors from the component.
ensureBehaviors() (opens new window) Makes sure that the behaviors declared in behaviors() (opens new window) are attached to this component.
generateToken() Generates a new user session token.
getBehavior() (opens new window) Returns the named behavior object.
getBehaviors() (opens new window) Returns all behaviors attached to this component.
getElevatedSessionTimeout() Returns how many seconds are left in the current elevated user session.
getHasElevatedSession() Returns whether the user currently has an elevated session.
getId() (opens new window) Returns a value that uniquely represents the user.
getIdentity() (opens new window) Returns the identity object associated with the currently logged-in user.
getIsAdmin() Returns whether the current user is an admin.
getIsGuest() Returns a value indicating whether the user is a guest (not authenticated).
getRemainingSessionTime() Returns how many seconds are left in the current user session.
getRememberedUsername() Returns the username of the account that the browser was last logged in as.
getReturnUrl() Returns the URL that the browser should be redirected to after successful login.
guestRequired() Redirects the user browser away from a guest page.
hasEventHandlers() (opens new window) Returns a value indicating whether there is any handler attached to the named event.
hasMethod() (opens new window) Returns a value indicating whether a method is defined.
hasProperty() (opens new window) Returns a value indicating whether a property is defined.
init() (opens new window) Initializes the object.
login() (opens new window) Logs in a user.
loginByAccessToken() (opens new window) Logs in a user by the given access token.
loginByUserId() Logs in a user by their ID.
loginRequired() (opens new window) Redirects the user browser to the login page.
logout() (opens new window) Logs out the current user.
off() (opens new window) Detaches an existing event handler from this component.
on() (opens new window) Attaches an event handler to an event.
removeReturnUrl() Removes the stored return URL, if there is one.
saveDebugPreferencesToSession() Saves the logged-in user’s Debug toolbar preferences to the session.
sendUsernameCookie() Sends a username cookie.
setIdentity() (opens new window) Sets the user identity object.
setReturnUrl() (opens new window) Remembers the URL in the session so that it can be retrieved back later by getReturnUrl() (opens new window).
startElevatedSession() Starts an elevated user session for the current user.
switchIdentity() Switches to a new identity for the current user.
trigger() (opens new window) Triggers an event.

# checkPermission()

Returns whether the current user has a given permission.

View source (opens new window)

Arguments

Returns

boolean (opens new window) – Whether the current user has the permission.

# destroyDebugPreferencesInSession()

DEPRECATED

Deprecated in 3.5.0

Removes the debug preferences from the session.

View source (opens new window)

# generateToken()

Since
3.1.1

Generates a new user session token.

View source (opens new window)

Arguments

# getElevatedSessionTimeout()

Returns how many seconds are left in the current elevated user session.

View source (opens new window)

Returns

integer (opens new window), boolean (opens new window) – The number of seconds left in the current elevated user session or false if it has been disabled.

# getHasElevatedSession()

Returns whether the user currently has an elevated session.

View source (opens new window)

Returns

boolean (opens new window) – Whether the user currently has an elevated session

# getIsAdmin()

Returns whether the current user is an admin.

View source (opens new window)

Returns

boolean (opens new window) – Whether the current user is an admin.

# getIsGuest()

Returns a value indicating whether the user is a guest (not authenticated).

View source (opens new window)

Returns

boolean (opens new window) – Whether the current user is a guest.

Example

 

$isGuest = Craft::$app->user->isGuest;

# getRemainingSessionTime()

Returns how many seconds are left in the current user session.

View source (opens new window)

Returns

integer (opens new window) – The seconds left in the session, or -1 if their session will expire when their HTTP session ends.

# getRememberedUsername()

Returns the username of the account that the browser was last logged in as.

View source (opens new window)

Returns

string (opens new window), null (opens new window)

Example

$username = Craft::$app->user->rememberedUsername;

# getReturnUrl()

Returns the URL that the browser should be redirected to after successful login.

This method reads the return URL from the session. It is usually used by the login action which may call this method to redirect the browser to where it goes after successful authentication.

View source (opens new window)

Arguments

Returns

string (opens new window) – The URL that the user should be redirected to after login.

# guestRequired()

Since
3.4.0

Redirects the user browser away from a guest page.

View source (opens new window)

Returns

craft\web\Response – The redirection response

Throws

# loginByUserId()

Logs in a user by their ID.

View source (opens new window)

Arguments

Returns

boolean (opens new window) – Whether the user is logged in

# removeReturnUrl()

Removes the stored return URL, if there is one.

See also getReturnUrl() View source (opens new window)

# saveDebugPreferencesToSession()

DEPRECATED

Deprecated in 3.5.0

Saves the logged-in user’s Debug toolbar preferences to the session.

View source (opens new window)

# sendUsernameCookie()

Sends a username cookie.

This method is used after a user is logged in. It saves the logged-in user's username in a cookie, so that login forms can remember the initial Username value on login forms.

See also afterLogin() View source (opens new window)

Arguments

# startElevatedSession()

Starts an elevated user session for the current user.

View source (opens new window)

Arguments

Returns

boolean (opens new window) – Whether the password was valid, and the user session has been elevated

Throws

# switchIdentity()

Switches to a new identity for the current user.

When enableSession (opens new window) is true, this method may use session and/or cookie to store the user identity information, according to the value of $duration. Please refer to login() (opens new window) for more details.

This method is mainly called by login() (opens new window), logout() (opens new window) and loginByCookie() (opens new window) when the current user needs to be associated with the corresponding identity information.

View source (opens new window)

Arguments

# Protected Methods

Method Description
afterLogin() This method is called after the user is successfully logged in.
afterLogout() This method is invoked right after a user is logged out via logout() (opens new window).
beforeLogin() This method is called before logging in a user.
beforeLogout() This method is invoked when calling logout() (opens new window) to log out a user.
checkRedirectAcceptable() (opens new window) Checks if the Accept header contains a content type that allows redirection to the login page.
getAccessChecker() (opens new window) Returns the access checker used for checking access.
getAuthManager() (opens new window) Returns auth manager associated with the user component.
getIdentityAndDurationFromCookie() (opens new window) Determines if an identity cookie has a valid format and contains a valid auth key.
loginByCookie() (opens new window) Logs in a user by cookie.
regenerateCsrfToken() (opens new window) Regenerates CSRF token
removeIdentityCookie() (opens new window) Removes the identity cookie.
renewAuthStatus() Updates the authentication status using the information from session and cookie.
renewIdentityCookie() (opens new window) Renews the identity cookie.
sendIdentityCookie() (opens new window) Sends an identity cookie.

# afterLogin()

This method is called after the user is successfully logged in.

The default implementation will trigger the EVENT_AFTER_LOGIN (opens new window) event. If you override this method, make sure you call the parent implementation so that the event is triggered.

View source (opens new window)

Arguments

# afterLogout()

This method is invoked right after a user is logged out via logout() (opens new window).

The default implementation will trigger the EVENT_AFTER_LOGOUT (opens new window) event. If you override this method, make sure you call the parent implementation so that the event is triggered.

View source (opens new window)

Arguments

# beforeLogin()

This method is called before logging in a user.

The default implementation will trigger the EVENT_BEFORE_LOGIN (opens new window) event. If you override this method, make sure you call the parent implementation so that the event is triggered.

View source (opens new window)

Arguments

Returns

boolean (opens new window) – Whether the user should continue to be logged in

# beforeLogout()

This method is invoked when calling logout() (opens new window) to log out a user.

The default implementation will trigger the EVENT_BEFORE_LOGOUT (opens new window) event. If you override this method, make sure you call the parent implementation so that the event is triggered.

View source (opens new window)

Arguments

Returns

boolean (opens new window) – Whether the user should continue to be logged out

# renewAuthStatus()

Updates the authentication status using the information from session and cookie.

This method will try to determine the user identity using the idParam (opens new window) session variable.

If authTimeout (opens new window) is set, this method will refresh the timer.

If the user identity cannot be determined by session, this method will try to login by cookie (opens new window) if enableAutoLogin (opens new window) is true.

View source (opens new window)

# Constants

Constant Description
EVENT_AFTER_LOGIN
EVENT_AFTER_LOGOUT
EVENT_BEFORE_LOGIN
EVENT_BEFORE_LOGOUT