Class craft\services\Users
- Inheritance
- craft\services\Users » yii\base\Component » yii\base\BaseObject
- Implements
- yii\base\Configurable
- Available since version
- 3.0
- Source Code
- https://github.com/craftcms/cms/blob/master/src/services/Users.php
The Users service provides APIs for managing users.
An instance of the Users service is globally accessible in Craft via Craft::$app->users.
| Method | Description | Defined By |
|---|---|---|
__call() |
Calls the named method which is not a class method. | yii\base\BaseObject |
__clone() |
This method is called after the object is created by cloning an existing one. | yii\base\Component |
__construct() |
Constructor. | yii\base\BaseObject |
__get() |
Returns the value of an object property. | yii\base\BaseObject |
__isset() |
Checks if a property is set, i.e. defined and not null. | yii\base\BaseObject |
__set() |
Sets value of an object property. | yii\base\BaseObject |
__unset() |
Sets an object property to null. | yii\base\BaseObject |
activateUser() |
Activates a user, bypassing email verification. | craft\services\Users |
assignUserToDefaultGroup() |
Assigns a user to the default user group. | craft\services\Users |
assignUserToGroups() |
Assigns a user to a given list of user groups. | craft\services\Users |
attachBehavior() |
Attaches a behavior to this component. | yii\base\Component |
attachBehaviors() |
Attaches a list of behaviors to the component. | yii\base\Component |
behaviors() |
Returns a list of behaviors that this component should behave as. | yii\base\Component |
canGetProperty() |
Returns a value indicating whether a property can be read. | yii\base\BaseObject |
canSetProperty() |
Returns a value indicating whether a property can be set. | yii\base\BaseObject |
className() |
Returns the fully qualified name of this class. | yii\base\BaseObject |
deleteUserPhoto() |
Deletes a user’s photo. | craft\services\Users |
detachBehavior() |
Detaches a behavior from the component. | yii\base\Component |
detachBehaviors() |
Detaches all behaviors from the component. | yii\base\Component |
ensureBehaviors() |
Makes sure that the behaviors declared in behaviors() are attached to this component. | yii\base\Component |
getBehavior() |
Returns the named behavior object. | yii\base\Component |
getBehaviors() |
Returns all behaviors attached to this component. | yii\base\Component |
getEmailVerifyUrl() |
Sets a new verification code on a user, and returns their new Email Verification URL. | craft\services\Users |
getPasswordResetUrl() |
Sets a new verification code on a user, and returns their new Password Reset URL. | craft\services\Users |
getUserById() |
Returns a user by their ID. | craft\services\Users |
getUserByUid() |
Returns a user by their UID. | craft\services\Users |
getUserByUsernameOrEmail() |
Returns a user by their username or email. | craft\services\Users |
getUserPreference() |
Returns one of a user’s preferences by its key. | craft\services\Users |
getUserPreferences() |
Returns a user’s preferences. | craft\services\Users |
handleInvalidLogin() |
Handles an invalid login for a user. | craft\services\Users |
handleValidLogin() |
Handles a valid login for a user. | craft\services\Users |
hasEventHandlers() |
Returns a value indicating whether there is any handler attached to the named event. | yii\base\Component |
hasMethod() |
Returns a value indicating whether a method is defined. | yii\base\BaseObject |
hasProperty() |
Returns a value indicating whether a property is defined. | yii\base\BaseObject |
hasUserShunnedMessage() |
Returns whether a message is shunned for a user. | craft\services\Users |
init() |
Initializes the object. | yii\base\BaseObject |
isVerificationCodeValidForUser() |
Returns whether a verification code is valid for the given user. | craft\services\Users |
off() |
Detaches an existing event handler from this component. | yii\base\Component |
on() |
Attaches an event handler to an event. | yii\base\Component |
purgeExpiredPendingUsers() |
Deletes any pending users that have shown zero sense of urgency and are just taking up space. | craft\services\Users |
saveUserPhoto() |
Crops and saves a user’s photo. | craft\services\Users |
saveUserPreferences() |
Saves a user’s preferences. | craft\services\Users |
sendActivationEmail() |
Sends a new account activation email for a user, regardless of their status. | craft\services\Users |
sendNewEmailVerifyEmail() |
Sends a new email verification email to a user, regardless of their status. | craft\services\Users |
sendPasswordResetEmail() |
Sends a password reset email to a user. | craft\services\Users |
setVerificationCodeOnUser() |
Sets a new verification code on the user's record. | craft\services\Users |
shunMessageForUser() |
Shuns a message for a user. | craft\services\Users |
suspendUser() |
Suspends a user. | craft\services\Users |
trigger() |
Triggers an event. | yii\base\Component |
unlockUser() |
Unlocks a user, bypassing the cooldown phase. | craft\services\Users |
unshunMessageForUser() |
Un-shuns a message for a user. | craft\services\Users |
unsuspendUser() |
Unsuspends a user. | craft\services\Users |
verifyEmailForUser() |
If 'unverifiedEmail' is set on the User, then this method will transfer it to the official email property and clear the unverified one. | craft\services\Users |
| Event | Type | Description | Defined By |
|---|---|---|---|
EVENT_AFTER_ACTIVATE_USER |
craft\events\UserEvent | The event that is triggered after a user is activated. | craft\services\Users |
EVENT_AFTER_ASSIGN_USER_TO_DEFAULT_GROUP |
craft\events\UserAssignGroupEvent | The event that is triggered after a user is assigned to the default user group. | craft\services\Users |
EVENT_AFTER_ASSIGN_USER_TO_GROUPS |
\craft\services\AssignUserGroupEvent | The event that is triggered after a user is assigned to some user groups. | craft\services\Users |
EVENT_AFTER_LOCK_USER |
craft\events\UserEvent | The event that is triggered after a user is locked. | craft\services\Users |
EVENT_AFTER_SUSPEND_USER |
craft\events\UserEvent | The event that is triggered after a user is suspended. | craft\services\Users |
EVENT_AFTER_UNLOCK_USER |
craft\events\UserEvent | The event that is triggered after a user is unlocked. | craft\services\Users |
EVENT_AFTER_UNSUSPEND_USER |
craft\events\UserEvent | The event that is triggered after a user is unsuspended. | craft\services\Users |
EVENT_AFTER_VERIFY_EMAIL |
craft\events\UserEvent | The event that is triggered after a user's email is verified. | craft\services\Users |
EVENT_BEFORE_ACTIVATE_USER |
craft\events\UserEvent | The event that is triggered before a user is activated. | craft\services\Users |
EVENT_BEFORE_ASSIGN_USER_TO_DEFAULT_GROUP |
craft\events\UserAssignGroupEvent | The event that is triggered before a user is assigned to the default user group. | craft\services\Users |
EVENT_BEFORE_ASSIGN_USER_TO_GROUPS |
\craft\services\AssignUserGroupEvent | The event that is triggered before a user is assigned to some user groups. | craft\services\Users |
EVENT_BEFORE_SUSPEND_USER |
craft\events\UserEvent | The event that is triggered before a user is suspended. | craft\services\Users |
EVENT_BEFORE_UNLOCK_USER |
craft\events\UserEvent | The event that is triggered before a user is unlocked. | craft\services\Users |
EVENT_BEFORE_UNSUSPEND_USER |
craft\events\UserEvent | The event that is triggered before a user is unsuspended. | craft\services\Users |
EVENT_BEFORE_VERIFY_EMAIL |
craft\events\UserEvent | The event that is triggered before a user's email is verified. | craft\services\Users |
Method Details
activateUser()
public method
#
Activates a user, bypassing email verification.
public boolean activateUser ( craft\elements\User $user )$user |
craft\elements\User | The user. |
| return | boolean | Whether the user was activated successfully. |
|---|---|---|
| throws | Throwable | if reasons |
assignUserToDefaultGroup()
public method
#
Assigns a user to the default user group.
This method is called toward the end of a public registration request.
public boolean assignUserToDefaultGroup ( craft\elements\User $user )$user |
craft\elements\User | The user that was just registered. |
| return | boolean | Whether the user was assigned to the default group. |
|---|
assignUserToGroups()
public method
#
Assigns a user to a given list of user groups.
public boolean assignUserToGroups ( \craft\services\int $userId, array $groupIds )$userId |
integer | The user’s ID |
$groupIds |
integer[] | The groups’ IDs. Pass an empty array to remove a user from all groups. |
| return | boolean | Whether the users were successfully assigned to the groups. |
|---|
deleteUserPhoto()
public method
#
Deletes a user’s photo.
public boolean deleteUserPhoto ( craft\elements\User $user )$user |
craft\elements\User | The user |
| return | boolean | Whether the user’s photo was deleted successfully |
|---|
getEmailVerifyUrl()
public method
#
Sets a new verification code on a user, and returns their new Email Verification URL.
public string getEmailVerifyUrl ( craft\elements\User $user )$user |
craft\elements\User | The user that should get the new Email Verification URL. |
| return | string | The new Email Verification URL. |
|---|
getPasswordResetUrl()
public method
#
Sets a new verification code on a user, and returns their new Password Reset URL.
public string getPasswordResetUrl ( craft\elements\User $user )$user |
craft\elements\User | The user that should get the new Password Reset URL |
| return | string | The new Password Reset URL. |
|---|
getUserById()
public method
#
Returns a user by their ID.
$user = Craft::$app->users->getUserById($userId);
public craft\elements\User, null getUserById ( \craft\services\int $userId )$userId |
integer | The user’s ID. |
| return | craft\elements\User, null | The user with the given ID, or null if a user could not be found.
|
|---|
getUserByUid()
public method
#
Returns a user by their UID.
$user = Craft::$app->users->getUserByUid($userUid);
public craft\elements\User, null getUserByUid ( \craft\services\string $uid )$uid |
string | The user’s UID. |
| return | craft\elements\User, null | The user with the given UID, or null if a user could not be found.
|
|---|
getUserByUsernameOrEmail()
public method
#
Returns a user by their username or email.
$user = Craft::$app->users->getUserByUsernameOrEmail($loginName);
public craft\elements\User, null getUserByUsernameOrEmail ( \craft\services\string $usernameOrEmail )$usernameOrEmail |
string | The user’s username or email. |
| return | craft\elements\User, null | The user with the given username/email, or null if a user could not be found.
|
|---|
getUserPreference()
public method
#
Returns one of a user’s preferences by its key.
public mixed getUserPreference ( \craft\services\int $userId = null, \craft\services\string $key, $default = null )$userId |
integer, null | The user’s ID |
$key |
string | The preference’s key |
$default |
mixed | The default value, if the preference hasn’t been set |
| return | mixed | The user’s preference |
|---|
getUserPreferences()
public method
#
Returns a user’s preferences.
public array getUserPreferences ( \craft\services\int $userId = null )$userId |
integer, null | The user’s ID |
| return | array | The user’s preferences |
|---|
handleInvalidLogin()
public method
#
Handles an invalid login for a user.
public void handleInvalidLogin ( craft\elements\User $user )$user |
craft\elements\User | The user |
handleValidLogin()
public method
#
Handles a valid login for a user.
public void handleValidLogin ( craft\elements\User $user )$user |
craft\elements\User | The user |
hasUserShunnedMessage()
public method
#
Returns whether a message is shunned for a user.
public boolean hasUserShunnedMessage ( \craft\services\int $userId, \craft\services\string $message )$userId |
integer | The user’s ID. |
$message |
string | The message to check. |
| return | boolean | Whether the user has shunned the message. |
|---|
isVerificationCodeValidForUser()
public method
#
Returns whether a verification code is valid for the given user.
This method first checks if the code has expired past the verificationCodeDuration config setting. If it is still valid, then, the checks the validity of the contents of the code.
public boolean isVerificationCodeValidForUser ( craft\elements\User $user, \craft\services\string $code )$user |
craft\elements\User | The user to check the code for. |
$code |
string | The verification code to check for. |
| return | boolean | Whether the code is still valid. |
|---|
purgeExpiredPendingUsers()
public method
#
Deletes any pending users that have shown zero sense of urgency and are just taking up space.
This method will check the purgePendingUsersDuration 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.
public void purgeExpiredPendingUsers ( )
saveUserPhoto()
public method
#
Crops and saves a user’s photo.
public void saveUserPhoto ( \craft\services\string $fileLocation, craft\elements\User $user, \craft\services\string $filename = '' )$fileLocation |
string | The local image path on server |
$user |
craft\elements\User | The user. |
$filename |
string | Name of the file to use, defaults to filename of $imagePath |
| throws | craft\errors\ImageException | if the file provided is not a manipulatable image |
|---|---|---|
| throws | craft\errors\VolumeException | if the user photo Volume is not provided or is invalid |
saveUserPreferences()
public method
#
Saves a user’s preferences.
public void saveUserPreferences ( craft\elements\User $user, array $preferences )$user |
craft\elements\User | The user |
$preferences |
array | The user’s new preferences |
sendActivationEmail()
public method
#
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.
public boolean sendActivationEmail ( craft\elements\User $user )$user |
craft\elements\User | The user to send the activation email to. |
| return | boolean | Whether the email was sent successfully. |
|---|
sendNewEmailVerifyEmail()
public method
#
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.
public boolean sendNewEmailVerifyEmail ( craft\elements\User $user )$user |
craft\elements\User | The user to send the activation email to. |
| return | boolean | Whether the email was sent successfully. |
|---|
sendPasswordResetEmail()
public method
#
Sends a password reset email to a user.
A new verification code will generated for the user overwriting any existing one.
public boolean sendPasswordResetEmail ( craft\elements\User $user )$user |
craft\elements\User | The user to send the forgot password email to. |
| return | boolean | Whether the email was sent successfully. |
|---|
setVerificationCodeOnUser()
public method
#
Sets a new verification code on the user's record.
public string setVerificationCodeOnUser ( craft\elements\User $user )$user |
craft\elements\User | The user. |
| return | string | The user’s brand new verification code. |
|---|
shunMessageForUser()
public method
#
Shuns a message for a user.
public boolean shunMessageForUser ( \craft\services\int $userId, \craft\services\string $message, DateTime $expiryDate = null )$userId |
integer | The user’s ID. |
$message |
string | The message to be shunned. |
$expiryDate |
DateTime, null | When the message should be un-shunned. Defaults to null (never un-shun).
|
| return | boolean | Whether the message was shunned successfully. |
|---|
suspendUser()
public method
#
Suspends a user.
public boolean suspendUser ( craft\elements\User $user )$user |
craft\elements\User | The user. |
| return | boolean | Whether the user was suspended successfully. |
|---|---|---|
| throws | Throwable | if reasons |
unlockUser()
public method
#
Unlocks a user, bypassing the cooldown phase.
public boolean unlockUser ( craft\elements\User $user )$user |
craft\elements\User | The user. |
| return | boolean | Whether the user was unlocked successfully. |
|---|---|---|
| throws | Throwable | if reasons |
unshunMessageForUser()
public method
#
Un-shuns a message for a user.
public boolean unshunMessageForUser ( \craft\services\int $userId, \craft\services\string $message )$userId |
integer | The user’s ID. |
$message |
string | The message to un-shun. |
| return | boolean | Whether the message was un-shunned successfully. |
|---|
unsuspendUser()
public method
#
Unsuspends a user.
public boolean unsuspendUser ( craft\elements\User $user )$user |
craft\elements\User | The user. |
| return | boolean | Whether the user was unsuspended successfully. |
|---|---|---|
| throws | Throwable | if reasons |
verifyEmailForUser()
public method
#
If 'unverifiedEmail' is set on the User, then this method will transfer it to the official email property and clear the unverified one.
public boolean verifyEmailForUser ( craft\elements\User $user )$user |
craft\elements\User |
Event Details
EVENT_AFTER_ACTIVATE_USER
event of type craft\events\UserEvent
#
The event that is triggered after a user is activated.
EVENT_AFTER_ASSIGN_USER_TO_DEFAULT_GROUP
event of type craft\events\UserAssignGroupEvent
#
The event that is triggered after a user is assigned to the default user group.
EVENT_AFTER_ASSIGN_USER_TO_GROUPS
event of type \craft\services\AssignUserGroupEvent
#
The event that is triggered after a user is assigned to some user groups.
EVENT_AFTER_LOCK_USER
event of type craft\events\UserEvent
#
The event that is triggered after a user is locked.
EVENT_AFTER_SUSPEND_USER
event of type craft\events\UserEvent
#
The event that is triggered after a user is suspended.
EVENT_AFTER_UNLOCK_USER
event of type craft\events\UserEvent
#
The event that is triggered after a user is unlocked.
EVENT_AFTER_UNSUSPEND_USER
event of type craft\events\UserEvent
#
The event that is triggered after a user is unsuspended.
EVENT_AFTER_VERIFY_EMAIL
event of type craft\events\UserEvent
#
The event that is triggered after a user's email is verified.
EVENT_BEFORE_ACTIVATE_USER
event of type craft\events\UserEvent
#
The event that is triggered before a user is activated.
You may set craft\events\UserEvent::$isValid to false to prevent the user from getting activated.
EVENT_BEFORE_ASSIGN_USER_TO_DEFAULT_GROUP
event of type craft\events\UserAssignGroupEvent
#
The event that is triggered before a user is assigned to the default user group.
You may set craft\events\UserAssignGroupEvent::$isValid to false to prevent the user from getting assigned to the default
user group.
EVENT_BEFORE_ASSIGN_USER_TO_GROUPS
event of type \craft\services\AssignUserGroupEvent
#
The event that is triggered before a user is assigned to some user groups.
You may set \craft\services\AssignUserGroupEvent::isValid to false to prevent the user from getting assigned to the groups.
EVENT_BEFORE_SUSPEND_USER
event of type craft\events\UserEvent
#
The event that is triggered before a user is suspended.
You may set craft\events\UserEvent::$isValid to false to prevent the user from getting suspended.
EVENT_BEFORE_UNLOCK_USER
event of type craft\events\UserEvent
#
The event that is triggered before a user is unlocked.
You may set craft\events\UserEvent::$isValid to false to prevent the user from getting unlocked.
EVENT_BEFORE_UNSUSPEND_USER
event of type craft\events\UserEvent
#
The event that is triggered before a user is unsuspended.
You may set craft\events\UserEvent::$isValid to false to prevent the user from getting unsuspended.
EVENT_BEFORE_VERIFY_EMAIL
event of type craft\events\UserEvent
#
The event that is triggered before a user's email is verified.