Users

Type
Class
Namespace
craft\services
Inherits
craft\services\Users » yii\base\Component » yii\base\BaseObject
Implements
yii\base\Configurable
Since
3.0

The Users service provides APIs for managing users.

An instance of the Users service is globally accessible in Craft via Craft::$app->users.

View source

Public Properties

PropertyDescription
$behaviorsyii\base\Behavior – List of behaviors attached to this component
$userPreferencesarray – The user’s preferences
$verificationCodeOnUsercraft\elements\User – The user.

$userPreferences

Type
array
Access
Read-only

The user’s preferences

View source

Signature

public array getUserPreferences ( \craft\services\int $userId = null )

$verificationCodeOnUser

Type
craft\elements\User
Access
Write-only

The user.

View source

Signature

public string setVerificationCodeOnUser ( craft\elements\User $user )

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 an object property.
__isset()Checks if a property is set, i.e. defined and not null.
__set()Sets value of an object property.
__unset()Sets an object property to null.
activateUser()Activates a user, bypassing email verification.
assignUserToDefaultGroup()Assigns a user to the default user group.
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.
canSetProperty()Returns a value indicating whether a property can be set.
className()Returns the fully qualified name of this class.
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.
getBehavior()Returns the named behavior object.
getBehaviors()Returns all behaviors attached to this component.
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.
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.
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.
purgeExpiredPendingUsers()Deletes any pending users that have shown zero sense of urgency and are just taking up space.
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

Signature

public boolean activateUser ( craft\elements\User $user )

assignUserToDefaultGroup()

Assigns a user to the default user group. 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.

Signature

public boolean assignUserToDefaultGroup ( craft\elements\User $user )

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.

Signature

public boolean assignUserToGroups ( \craft\services\int $userId, array $groupIds )

deleteUserPhoto()

Deletes a user’s photo.

View source

Arguments

Returns

boolean – Whether the user’s photo was deleted successfully

Signature

public boolean deleteUserPhoto ( craft\elements\User $user )

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.

Signature

public string getEmailVerifyUrl ( craft\elements\User $user )

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.

Signature

public string getPasswordResetUrl ( craft\elements\User $user )

getUserById()

Returns a user by their ID.

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

Signature

public craft\elements\User, null getUserById ( \craft\services\int $userId )

getUserByUid()

Returns a user by their UID.

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

Signature

public craft\elements\User, null getUserByUid ( \craft\services\string $uid )

getUserByUsernameOrEmail()

Returns a user by their username or email.

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

Signature

public craft\elements\User, null getUserByUsernameOrEmail ( \craft\services\string $usernameOrEmail )

getUserPreference()

Returns one of a user’s preferences by its key.

View source

Arguments

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

Returns

mixed – The user’s preference

Signature

public mixed getUserPreference ( \craft\services\int $userId = null, \craft\services\string $key, $default = null )

getUserPreferences()

Returns a user’s preferences.

View source

Arguments

Returns

array – The user’s preferences

Signature

public array getUserPreferences ( \craft\services\int $userId = null )

handleInvalidLogin()

Handles an invalid login for a user.

View source

Arguments

Signature

public void handleInvalidLogin ( craft\elements\User $user )

handleValidLogin()

Handles a valid login for a user.

View source

Arguments

Signature

public void handleValidLogin ( craft\elements\User $user )

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.

Signature

public boolean hasUserShunnedMessage ( \craft\services\int $userId, \craft\services\string $message )

isVerificationCodeValidForUser()

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.

View source

Arguments

Returns

boolean – Whether the code is still valid.

Signature

public boolean isVerificationCodeValidForUser ( craft\elements\User $user, \craft\services\string $code )

purgeExpiredPendingUsers()

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.

View source

Signature

public void purgeExpiredPendingUsers ( )

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) – Name of the file to use, defaults to filename of $imagePath

Throws

Signature

public void saveUserPhoto ( \craft\services\string $fileLocation, craft\elements\User $user, \craft\services\string $filename = '' )

saveUserPreferences()

Saves a user’s preferences.

View source

Arguments

Signature

public void saveUserPreferences ( craft\elements\User $user, array $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

Arguments

Returns

boolean – Whether the email was sent successfully.

Signature

public boolean sendActivationEmail ( craft\elements\User $user )

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.

Signature

public boolean sendNewEmailVerifyEmail ( craft\elements\User $user )

sendPasswordResetEmail()

Sends a password reset email to a user. A new verification code will generated for the user overwriting any existing one.

View source

Arguments

Returns

boolean – Whether the email was sent successfully.

Signature

public boolean sendPasswordResetEmail ( craft\elements\User $user )

setVerificationCodeOnUser()

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

View source

Arguments

Returns

string – The user’s brand new verification code.

Signature

public string setVerificationCodeOnUser ( craft\elements\User $user )

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.

Signature

public boolean shunMessageForUser ( \craft\services\int $userId, \craft\services\string $message, DateTime $expiryDate = null )

suspendUser()

Suspends a user.

View source

Arguments

Returns

boolean – Whether the user was suspended successfully.

Throws

Signature

public boolean suspendUser ( craft\elements\User $user )

unlockUser()

Unlocks a user, bypassing the cooldown phase.

View source

Arguments

Returns

boolean – Whether the user was unlocked successfully.

Throws

Signature

public boolean unlockUser ( craft\elements\User $user )

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.

Signature

public boolean unshunMessageForUser ( \craft\services\int $userId, \craft\services\string $message )

unsuspendUser()

Unsuspends a user.

View source

Arguments

Returns

boolean – Whether the user was unsuspended successfully.

Throws

Signature

public boolean unsuspendUser ( craft\elements\User $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.

View source

Arguments

Returns

boolean

Signature

public boolean verifyEmailForUser ( craft\elements\User $user )

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\services\AssignUserGroupEvent

The event that is triggered after a user is assigned to some user groups.

EVENT_AFTER_LOCK_USER

Type
craft\events\UserEvent

The event that is triggered after a user is locked.

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\UserEvent::$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\UserAssignGroupEvent::$isValid to false to prevent the user from getting assigned to the default user group.

EVENT_BEFORE_ASSIGN_USER_TO_GROUPS

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

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

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

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

Type
craft\events\UserEvent

The event that is triggered before a user's email is verified.