Craft 4 Class Reference

Appearance

Users ​

Type
Class
Namespace
craft\services
Inherits
craft\services\Users » yii\base\Component » yii\base\BaseObject
Implements
yii\base\Configurable
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

Public Properties ​

PropertyDescription
behaviorsyii\base\Behavior – List of behaviors attached to this component.
verificationCodeOnUsercraft\elements\User – The user.

verificationCodeOnUser ​

Type
craft\elements\User
Default value
null
Access
Write-only

The user.

View source

Public Methods ​

MethodDescription
__call()Calls the named method which is not a class method.
__clone()This method is called after the object is created by cloning an existing one.
__construct()Constructor.
__get()Returns the value of a component property.
__isset()Checks if a property is set, i.e. defined and not null.
__set()Sets the value of a component property.
__unset()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()Attaches a behavior to this component.
attachBehaviors()Attaches a list of behaviors to the component.
behaviors()Returns a list of behaviors that this component should behave as.
canGetProperty()Returns a value indicating whether a property can be read.
canImpersonate()Returns whether a user is allowed to impersonate another user.
canSetProperty()Returns a value indicating whether a property can be set.
canSuspend()Returns whether the user can suspend the given user
className()Returns the fully qualified name of this class.
deactivateUser()Deactivates a user.
deleteUserPhoto()Deletes a user’s photo.
detachBehavior()Detaches a behavior from the component.
detachBehaviors()Detaches all behaviors from the component.
ensureBehaviors()Makes sure that the behaviors declared in behaviors() 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()Returns the named behavior object.
getBehaviors()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()Returns a value indicating whether there is any handler attached to the named event.
hasMethod()Returns a value indicating whether a method is defined.
hasProperty()Returns a value indicating whether a property is defined for this component.
hasUserShunnedMessage()Returns whether a message is shunned for a user.
init()Initializes the object.
isVerificationCodeValidForUser()Returns whether a verification code is valid for the given user.
off()Detaches an existing event handler from this component.
on()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()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

Arguments ​

Returns ​

boolean – Whether the user was activated successfully.

Throws ​

assignUserToDefaultGroup() ​

Assigns a user to the default user group(s).

This method is called toward the end of a public registration request.

View source

Arguments ​

Returns ​

boolean – Whether the user was assigned to the default group.

assignUserToGroups() ​

Assigns a user to a given list of user groups.

View source

Arguments ​

  • $userId (integer) – The user’s ID
  • $groupIds (integer[]) – The groups’ IDs. Pass an empty array to remove a user from all groups.

Returns ​

boolean – 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

Arguments ​

Returns ​

boolean

canSuspend() ​

Since
3.7.32

Returns whether the user can suspend the given user

View source

Arguments ​

Returns ​

boolean

deactivateUser() ​

Since
4.0.0

Deactivates a user.

View source

Arguments ​

Returns ​

boolean – Whether the user was deactivated successfully.

Throws ​

deleteUserPhoto() ​

Deletes a user’s photo.

View source

Arguments ​

Returns ​

boolean – 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

Arguments ​

Returns ​

craft\elements\User

Throws ​

getActivationUrl() ​

Sets a new verification code on a user, and returns their activation URL.

View source

Arguments ​

Returns ​

string

Throws ​

getDefaultUserGroups() ​

Since
4.5.4

Returns the default user groups that the given user should belong to.

View source

Arguments ​

Returns ​

craft\models\UserGroup[]

getEmailVerifyUrl() ​

Sets a new verification code on a user, and returns their new Email Verification URL.

View source

Arguments ​

Returns ​

string – The new Email Verification URL.

Throws ​

getPasswordResetUrl() ​

Sets a new verification code on a user, and returns their new Password Reset URL.

View source

Arguments ​

Returns ​

string – The new Password Reset URL.

Throws ​

getUserById() ​

Returns a user by their ID.

php
$user = Craft::$app->users->getUserById($userId);

View source

Arguments ​

  • $userId (integer) – The user’s ID.

Returns ​

craft\elements\User, null – The user with the given ID, or null if a user could not be found.

getUserByUid() ​

Returns a user by their UID.

php
$user = Craft::$app->users->getUserByUid($userUid);

View source

Arguments ​

  • $uid (string) – The user’s UID.

Returns ​

craft\elements\User, null – The user with the given UID, or null if a user could not be found.

getUserByUsernameOrEmail() ​

Returns a user by their username or email.

php
$user = Craft::$app->users->getUserByUsernameOrEmail($loginName);

View source

Arguments ​

  • $usernameOrEmail (string) – The user’s username or email.

Returns ​

craft\elements\User, null – 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

Arguments ​

  • $userId (integer) – The user’s ID
  • $key (string) – 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

Arguments ​

  • $userId (integer) – The user’s ID

Returns ​

array – The user’s preferences

handleChangedUserFieldLayout() ​

Handle user field layout changes.

View source

Arguments ​

handleInvalidLogin() ​

Handles an invalid login for a user.

View source

Arguments ​

handleValidLogin() ​

Handles a valid login for a user.

View source

Arguments ​

hasUserShunnedMessage() ​

Returns whether a message is shunned for a user.

View source

Arguments ​

  • $userId (integer) – The user’s ID.
  • $message (string) – The message to check.

Returns ​

boolean – 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 config setting. If it is still valid, then, the checks the validity of the contents of the code.

View source

Arguments ​

  • $user (craft\elements\User) – The user to check the code for.
  • $code (string) – The verification code to check for.

Returns ​

boolean – 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

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

relocateUserPhoto() ​

Since
3.5.14

Updates the location of a user’s photo.

View source

Arguments ​

removeCredentials() ​

Since
4.0.0

Removes credentials for a user.

View source

Arguments ​

Returns ​

boolean – Whether the user’s credentials were successfully removed.

Throws ​

saveLayout() ​

Save the user field layout

View source

Arguments ​

Returns ​

boolean

saveUserPhoto() ​

Crops and saves a user’s photo.

View source

Arguments ​

  • $fileLocation (string) – The local image path on server
  • $user (craft\elements\User) – The user.
  • $filename (string, null) – Name of the file to use, defaults to filename of $fileLocation

Throws ​

saveUserPreferences() ​

Saves a user’s preferences.

View source

Arguments ​

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

Arguments ​

Returns ​

boolean – Whether the email was sent successfully.

Throws ​

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

Arguments ​

Returns ​

boolean – Whether the email was sent successfully.

Throws ​

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

Arguments ​

Returns ​

boolean – Whether the email was sent successfully.

Throws ​

setVerificationCodeOnUser() ​

Sets a new verification code on the user’s record.

View source

Arguments ​

Returns ​

string – The user’s brand new verification code.

Throws ​

shunMessageForUser() ​

Shuns a message for a user.

View source

Arguments ​

  • $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).

Returns ​

boolean – Whether the message was shunned successfully.

suspendUser() ​

Suspends a user.

View source

Arguments ​

Returns ​

boolean – Whether the user was suspended successfully.

Throws ​

unlockUser() ​

Unlocks a user, bypassing the cooldown phase.

View source

Arguments ​

Returns ​

boolean – Whether the user was unlocked successfully.

Throws ​

unshunMessageForUser() ​

Un-shuns a message for a user.

View source

Arguments ​

  • $userId (integer) – The user’s ID.
  • $message (string) – The message to un-shun.

Returns ​

boolean – Whether the message was un-shunned successfully.

unsuspendUser() ​

Unsuspends a user.

View source

Arguments ​

Returns ​

boolean – Whether the user was unsuspended successfully.

Throws ​

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

Arguments ​

Returns ​

boolean

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