Users
- Type
- Class
- Namespace
- craft\services
- Inherits
- craft\services\Users » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)
- Implements
- yii\base\Configurable (opens new window)
- Since
- 3.0.0
The Users service provides APIs for managing users.
An instance of the service is available via Craft::$app->users
.
View source (opens new window)
# Public Properties
Property | Description |
---|---|
behaviors (opens new window) | yii\base\Behavior (opens new window) – List of behaviors attached to this component. |
verificationCodeOnUser | craft\elements\User – The user. |
# verificationCodeOnUser
- Type
- craft\elements\User
- Default value
null
- Access
- Write-only
The user.
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 a component property. |
__isset() (opens new window) | Checks if a property is set, i.e. defined and not null. |
__set() (opens new window) | Sets the value of a component property. |
__unset() (opens new window) | Sets a component property to be null. |
activateUser() | Activates a user, bypassing email verification. |
assignUserToDefaultGroup() | Assigns a user to the default user group(s). |
assignUserToGroups() | Assigns a user to a given list of user groups. |
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. |
canGetProperty() (opens new window) | Returns a value indicating whether a property can be read. |
canImpersonate() | Returns whether a user is allowed to impersonate another user. |
canSetProperty() (opens new window) | Returns a value indicating whether a property can be set. |
canSuspend() | Returns whether the user can suspend the given user |
className() (opens new window) | Returns the fully qualified name of this class. |
deactivateUser() | Deactivates a user. |
deleteUserPhoto() | Deletes a user’s photo. |
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. |
ensureUserByEmail() | Returns a user by an email address, creating one if none already exists. |
getActivationUrl() | Sets a new verification code on a user, and returns their activation URL. |
getBehavior() (opens new window) | Returns the named behavior object. |
getBehaviors() (opens new window) | Returns all behaviors attached to this component. |
getDefaultUserGroups() | Returns the default user groups that the given user should belong to. |
getEmailVerifyUrl() | Sets a new verification code on a user, and returns their new Email Verification URL. |
getPasswordResetUrl() | Sets a new verification code on a user, and returns their new Password Reset URL. |
getUserById() | Returns a user by their ID. |
getUserByUid() | Returns a user by their UID. |
getUserByUsernameOrEmail() | Returns a user by their username or email. |
getUserPreference() | Returns one of a user’s preferences by its key. |
getUserPreferences() | Returns a user’s preferences. |
handleChangedUserFieldLayout() | Handle user field layout changes. |
handleInvalidLogin() | Handles an invalid login for a user. |
handleValidLogin() | Handles a valid login for a user. |
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 for this component. |
hasUserShunnedMessage() | Returns whether a message is shunned for a user. |
init() (opens new window) | Initializes the object. |
isVerificationCodeValidForUser() | Returns whether a verification code is valid for the given user. |
off() (opens new window) | Detaches an existing event handler from this component. |
on() (opens new window) | Attaches an event handler to an event. |
pruneDeletedField() | |
purgeExpiredPendingUsers() | Deletes any pending users that have shown zero sense of urgency and are just taking up space. |
relocateUserPhoto() | Updates the location of a user’s photo. |
removeCredentials() | Removes credentials for a user. |
saveLayout() | Save the user field layout |
saveUserPhoto() | Crops and saves a user’s photo. |
saveUserPreferences() | Saves a user’s preferences. |
sendActivationEmail() | Sends a new account activation email for a user, regardless of their status. |
sendNewEmailVerifyEmail() | Sends a new email verification email to a user, regardless of their status. |
sendPasswordResetEmail() | Sends a password reset email to a user. |
setVerificationCodeOnUser() | Sets a new verification code on the user’s record. |
shunMessageForUser() | Shuns a message for a user. |
suspendUser() | Suspends a user. |
trigger() (opens new window) | Triggers an event. |
unlockUser() | Unlocks a user, bypassing the cooldown phase. |
unshunMessageForUser() | Un-shuns a message for a user. |
unsuspendUser() | Unsuspends a user. |
verifyEmailForUser() | If 'unverifiedEmail' is set on the User, then this method will transfer it to the official email property and clear the unverified one. |
# activateUser()
Activates a user, bypassing email verification.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user.
Returns
boolean (opens new window) – Whether the user was activated successfully.
Throws
- Throwable (opens new window)
if reasons
# assignUserToDefaultGroup()
Assigns a user to the default user group(s).
This method is called toward the end of a public registration request.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user that was just registered.
Returns
boolean (opens new window) – Whether the user was assigned to the default group.
# assignUserToGroups()
Assigns a user to a given list of user groups.
View source (opens new window)
Arguments
$userId
(integer (opens new window)) – The user’s ID$groupIds
(integer (opens new window)[]) – The groups’ IDs. Pass an empty array to remove a user from all groups.
Returns
boolean (opens new window) – Whether the users were successfully assigned to the groups.
# canImpersonate()
- Since
- 3.2.0
Returns whether a user is allowed to impersonate another user.
View source (opens new window)
Arguments
$impersonator
(craft\elements\User)$impersonatee
(craft\elements\User)
Returns
# canSuspend()
- Since
- 3.7.32
Returns whether the user can suspend the given user
View source (opens new window)
Arguments
$suspender
(craft\elements\User)$suspendee
(craft\elements\User)
Returns
# deactivateUser()
- Since
- 4.0.0
Deactivates a user.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user.
Returns
boolean (opens new window) – Whether the user was deactivated successfully.
Throws
- Throwable (opens new window)
if reasons
# deleteUserPhoto()
Deletes a user’s photo.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user
Returns
boolean (opens new window) – Whether the user’s photo was deleted successfully
# ensureUserByEmail()
- Since
- 4.0.0
Returns a user by an email address, creating one if none already exists.
View source (opens new window)
Arguments
$email
(string (opens new window))
Returns
Throws
- yii\base\InvalidArgumentException (opens new window)
if$email
is invalid - yii\base\Exception (opens new window)
if the user couldn’t be saved for some unexpected reason
# getActivationUrl()
Sets a new verification code on a user, and returns their activation URL.
View source (opens new window)
Arguments
$user
(craft\elements\User)
Returns
Throws
- craft\errors\InvalidElementException
if the user doesn't validate
# getDefaultUserGroups()
- Since
- 4.5.4
Returns the default user groups that the given user should belong to.
View source (opens new window)
Arguments
$user
(craft\elements\User)
Returns
# getEmailVerifyUrl()
Sets a new verification code on a user, and returns their new Email Verification URL.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user that should get the new Email Verification URL.
Returns
string (opens new window) – The new Email Verification URL.
Throws
- craft\errors\InvalidElementException
if the user doesn't validate
# getPasswordResetUrl()
Sets a new verification code on a user, and returns their new Password Reset URL.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user that should get the new Password Reset URL
Returns
string (opens new window) – The new Password Reset URL.
Throws
- craft\errors\InvalidElementException
if the user doesn't validate
# getUserById()
Returns a user by their ID.
$user = Craft::$app->users->getUserById($userId);
View source (opens new window)
Arguments
$userId
(integer (opens new window)) – The user’s ID.
Returns
craft\elements\User, null (opens new window) – The user with the given ID, or null
if a user could not be found.
# getUserByUid()
Returns a user by their UID.
$user = Craft::$app->users->getUserByUid($userUid);
View source (opens new window)
Arguments
$uid
(string (opens new window)) – The user’s UID.
Returns
craft\elements\User, null (opens new window) – The user with the given UID, or null
if a user could not be found.
# getUserByUsernameOrEmail()
Returns a user by their username or email.
$user = Craft::$app->users->getUserByUsernameOrEmail($loginName);
View source (opens new window)
Arguments
$usernameOrEmail
(string (opens new window)) – The user’s username or email.
Returns
craft\elements\User, null (opens new window) – The user with the given username/email, or null
if a user could not be found.
# getUserPreference()
Returns one of a user’s preferences by its key.
View source (opens new window)
Arguments
$userId
(integer (opens new window)) – The user’s ID$key
(string (opens new window)) – The preference’s key$default
(mixed
) – The default value, if the preference hasn’t been set
Returns
mixed
– The user’s preference
# getUserPreferences()
Returns a user’s preferences.
View source (opens new window)
Arguments
$userId
(integer (opens new window)) – The user’s ID
Returns
array (opens new window) – The user’s preferences
# handleChangedUserFieldLayout()
Handle user field layout changes.
View source (opens new window)
Arguments
$event
(craft\events\ConfigEvent)
# handleInvalidLogin()
Handles an invalid login for a user.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user
# handleValidLogin()
Handles a valid login for a user.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user
# hasUserShunnedMessage()
Returns whether a message is shunned for a user.
View source (opens new window)
Arguments
$userId
(integer (opens new window)) – The user’s ID.$message
(string (opens new window)) – The message to check.
Returns
boolean (opens new window) – Whether the user has shunned the message.
# isVerificationCodeValidForUser()
Returns whether a verification code is valid for the given user.
This method first checks if the code has expired past the config4:verificationCodeDuration (opens new window) config setting. If it is still valid, then, the checks the validity of the contents of the code.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user to check the code for.$code
(string (opens new window)) – The verification code to check for.
Returns
boolean (opens new window) – Whether the code is still valid.
# pruneDeletedField()
DEPRECATED
Deprecated in 4.0.5. Unused fields will be pruned automatically as field layouts are resaved.
View source (opens new window)
# purgeExpiredPendingUsers()
Deletes any pending users that have shown zero sense of urgency and are just taking up space.
This method will check the config4:purgePendingUsersDuration (opens new window) config setting, and if it is set to a valid duration, it will delete any user accounts that were created that duration ago, and have still not activated their account.
View source (opens new window)
# relocateUserPhoto()
- Since
- 3.5.14
Updates the location of a user’s photo.
View source (opens new window)
Arguments
$user
(craft\elements\User)
# removeCredentials()
- Since
- 4.0.0
Removes credentials for a user.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user that should have credentials removed.
Returns
boolean (opens new window) – Whether the user’s credentials were successfully removed.
Throws
# saveLayout()
Save the user field layout
View source (opens new window)
Arguments
$layout
(craft\models\FieldLayout)$runValidation
(boolean (opens new window)) – Whether the layout should be validated
Returns
# saveUserPhoto()
Crops and saves a user’s photo.
View source (opens new window)
Arguments
$fileLocation
(string (opens new window)) – The local image path on server$user
(craft\elements\User) – The user.$filename
(string (opens new window), null (opens new window)) – Name of the file to use, defaults to filename of$fileLocation
Throws
- craft\errors\ImageException
if the file provided is not a manipulatable image - craft\errors\VolumeException
if the user photo volume is not provided or is invalid
# saveUserPreferences()
Saves a user’s preferences.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user$preferences
(array (opens new window)) – The user’s new preferences
# sendActivationEmail()
Sends a new account activation email for a user, regardless of their status.
A new verification code will generated for the user overwriting any existing one.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user to send the activation email to.
Returns
boolean (opens new window) – Whether the email was sent successfully.
Throws
- craft\errors\InvalidElementException
if the user doesn't validate
# sendNewEmailVerifyEmail()
Sends a new email verification email to a user, regardless of their status.
A new verification code will generated for the user overwriting any existing one.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user to send the activation email to.
Returns
boolean (opens new window) – Whether the email was sent successfully.
Throws
- craft\errors\InvalidElementException
if the user doesn't validate
# sendPasswordResetEmail()
Sends a password reset email to a user.
A new verification code be will generated for the user, overwriting any existing one.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user to send the forgot password email to.
Returns
boolean (opens new window) – Whether the email was sent successfully.
Throws
- craft\errors\InvalidElementException
if the user doesn't validate
# setVerificationCodeOnUser()
Sets a new verification code on the user’s record.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user.
Returns
string (opens new window) – The user’s brand new verification code.
Throws
- craft\errors\InvalidElementException
if the user doesn't validate
# shunMessageForUser()
Shuns a message for a user.
View source (opens new window)
Arguments
$userId
(integer (opens new window)) – The user’s ID.$message
(string (opens new window)) – The message to be shunned.$expiryDate
(DateTime (opens new window), null (opens new window)) – When the message should be un-shunned. Defaults tonull
(never un-shun).
Returns
boolean (opens new window) – Whether the message was shunned successfully.
# suspendUser()
Suspends a user.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user.
Returns
boolean (opens new window) – Whether the user was suspended successfully.
Throws
- Throwable (opens new window)
if reasons
# unlockUser()
Unlocks a user, bypassing the cooldown phase.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user.
Returns
boolean (opens new window) – Whether the user was unlocked successfully.
Throws
- Throwable (opens new window)
if reasons
# unshunMessageForUser()
Un-shuns a message for a user.
View source (opens new window)
Arguments
$userId
(integer (opens new window)) – The user’s ID.$message
(string (opens new window)) – The message to un-shun.
Returns
boolean (opens new window) – Whether the message was un-shunned successfully.
# unsuspendUser()
Unsuspends a user.
View source (opens new window)
Arguments
$user
(craft\elements\User) – The user.
Returns
boolean (opens new window) – Whether the user was unsuspended successfully.
Throws
- Throwable (opens new window)
if reasons
# verifyEmailForUser()
If 'unverifiedEmail' is set on the User, then this method will transfer it to the official email property and clear the unverified one.
View source (opens new window)
Arguments
$user
(craft\elements\User)
Returns
# Events
# EVENT_AFTER_ACTIVATE_USER
The event that is triggered after a user is activated.
# EVENT_AFTER_ASSIGN_USER_TO_DEFAULT_GROUP
The event that is triggered after a user is assigned to the default user group.
# EVENT_AFTER_ASSIGN_USER_TO_GROUPS
The event that is triggered after a user is assigned to some user groups.
# EVENT_AFTER_DEACTIVATE_USER
- Type
- craft\events\UserEvent
- Since
- 4.0.0
The event that is triggered after a user is deactivated.
# EVENT_AFTER_DELETE_USER_PHOTO
- Type
- craft\events\UserPhotoEvent
- Since
- 4.4.0
The event that is triggered after a user photo is deleted.
# EVENT_AFTER_LOCK_USER
The event that is triggered after a user is locked.
# EVENT_AFTER_SAVE_USER_PHOTO
- Type
craft\services\UserSavePhotoEvent
- Since
- 4.4.0
The event that is triggered after a user photo is saved.
# EVENT_AFTER_SUSPEND_USER
The event that is triggered after a user is suspended.
# EVENT_AFTER_UNLOCK_USER
The event that is triggered after a user is unlocked.
# EVENT_AFTER_UNSUSPEND_USER
The event that is triggered after a user is unsuspended.
# EVENT_AFTER_VERIFY_EMAIL
The event that is triggered after a user’s email is verified.
# EVENT_BEFORE_ACTIVATE_USER
The event that is triggered before a user is activated.
You may set craft\events\CancelableEvent::$isValid to false
to prevent the user from getting activated.
# EVENT_BEFORE_ASSIGN_USER_TO_DEFAULT_GROUP
The event that is triggered before a user is assigned to the default user group.
You may set craft\events\CancelableEvent::$isValid to false
to prevent the user from getting assigned to the default
user group.
# EVENT_BEFORE_ASSIGN_USER_TO_GROUPS
The event that is triggered before a user is assigned to some user groups.
You may set craft\events\CancelableEvent::$isValid to false
to prevent the user from getting assigned to the groups.
# EVENT_BEFORE_DEACTIVATE_USER
- Type
- craft\events\UserEvent
- Since
- 4.0.0
The event that is triggered before a user is deactivated.
You may set craft\events\UserEvent::$isValid to false
to prevent the user from getting deactivated.
# EVENT_BEFORE_DELETE_USER_PHOTO
- Type
- craft\events\UserPhotoEvent
- Since
- 4.4.0
The event that is triggered before a user photo is deleted.
# EVENT_BEFORE_SAVE_USER_PHOTO
- Type
craft\services\UserSavePhotoEvent
- Since
- 4.4.0
The event that is triggered before a user photo is saved.
# EVENT_BEFORE_SUSPEND_USER
The event that is triggered before a user is suspended.
You may set craft\events\CancelableEvent::$isValid to false
to prevent the user from getting suspended.
# EVENT_BEFORE_UNLOCK_USER
The event that is triggered before a user is unlocked.
You may set craft\events\CancelableEvent::$isValid to false
to prevent the user from getting unlocked.
# EVENT_BEFORE_UNSUSPEND_USER
The event that is triggered before a user is unsuspended.
You may set craft\events\CancelableEvent::$isValid to false
to prevent the user from getting unsuspended.
# EVENT_BEFORE_VERIFY_EMAIL
The event that is triggered before a user’s email is verified.
# EVENT_DEFINE_DEFAULT_USER_GROUPS
- Type
- craft\events\DefineUserGroupsEvent
- Since
- 4.5.4
The event that is triggered when defining the default user groups to assign to a publicly-registered user.
See also getDefaultUserGroups()