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

boolean (opens new window)

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

boolean (opens new window)

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

craft\elements\User

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

string (opens new window)

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

craft\models\UserGroup[]

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

• craft\errors\UserNotFoundException

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

boolean (opens new window)

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 to null (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

boolean (opens new window)

Events

EVENT_AFTER_ACTIVATE_USER

Type

craft\events\UserEvent

The event that is triggered after a user is activated.

EVENT_AFTER_ASSIGN_USER_TO_DEFAULT_GROUP

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

Type

craft\events\UserGroupsAssignEvent

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

Type

craft\events\UserEvent

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

Type

craft\events\UserEvent

The event that is triggered after a user is suspended.

EVENT_AFTER_UNLOCK_USER

Type

craft\events\UserEvent

The event that is triggered after a user is unlocked.

EVENT_AFTER_UNSUSPEND_USER

Type

craft\events\UserEvent

The event that is triggered after a user is unsuspended.

EVENT_AFTER_VERIFY_EMAIL

Type

craft\events\UserEvent

The event that is triggered after a user’s email is verified.

EVENT_BEFORE_ACTIVATE_USER

Type

craft\events\UserEvent

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

Type

craft\events\UserAssignGroupEvent

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

Type

craft\events\UserGroupsAssignEvent

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

Type

craft\events\UserEvent

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

Type

craft\events\UserEvent

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

Type

craft\events\UserEvent

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

Type

craft\events\UserEvent

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()