UsersService

Type

Class

Namespace

Craft

Inherits

Craft\UsersService » Craft\BaseApplicationComponent » CApplicationComponent (opens new window) » CComponent (opens new window)

Implements

IApplicationComponent

Since

1.0

UsersService provides APIs for managing users.

An instance of UsersService is globally accessible in Craft via {@link WebApp::users craft()->users}.

See also http://craftcms.com

View source (opens new window)

Public Properties

Property	Description
$behaviors (opens new window)	array (opens new window) – The behaviors that should be attached to this component.

Public Methods

Method	Description
__call() (opens new window)	Calls the named method which is not a class method.
__get() (opens new window)	Returns a property value, an event handler list or a behavior based on its name.
__isset() (opens new window)	Checks if a property value is null.
__set() (opens new window)	Sets value of a component property.
__unset() (opens new window)	Sets a component property to be null.
activateUser()	Activates a user, bypassing email verification.
asa() (opens new window)	Returns the named behavior object.
attachBehavior() (opens new window)	Attaches a behavior to this component.
attachBehaviors() (opens new window)	Attaches a list of behaviors to the component.
attachEventHandler() (opens new window)	Attaches an event handler to an event.
canGetProperty() (opens new window)	Determines whether a property can be read.
canSetProperty() (opens new window)	Determines whether a property can be set.
changePassword()	Changes a user’s password.
deleteUser()	Deletes 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.
detachEventHandler() (opens new window)	Detaches an existing event handler.
disableBehavior() (opens new window)	Disables an attached behavior.
disableBehaviors() (opens new window)	Disables all behaviors attached to this component.
enableBehavior() (opens new window)	Enables an attached behavior.
enableBehaviors() (opens new window)	Enables all behaviors attached to this component.
evaluateExpression() (opens new window)	Evaluates a PHP expression or callback under the context of this component.
getClient()	Returns the “Client” user account, if it has been created yet.
getEmailVerifyUrl()	Sets a new verification code on a user, and returns their new Email Verification URL.
getEventHandlers() (opens new window)	Returns the list of attached event handlers for an event.
getIsInitialized() (opens new window)	Checks if this application component has been initialized.
getPasswordResetUrl()	Sets a new verification code on a user, and returns their new Password Reset URL.
getUserByEmail()	Returns a user by their email.
getUserById()	Returns a user by their ID.
getUserByUid()	Returns a user by their UID.
getUserByUsernameOrEmail()	Returns a user by their username or email.
handleInvalidLogin()	Handles an invalid login for a user.
handleSuccessfulLogin()	Handles a successful login for a user.
hasEvent() (opens new window)	Determines whether an event is defined.
hasEventHandler() (opens new window)	Checks whether the named event has attached handlers.
hasProperty() (opens new window)	Determines whether a property is defined.
hasUserShunnedMessage()	Returns whether a message is shunned for a user.
init() (opens new window)	Initializes the application component.
isInitialized()	Checks if this application component has been initialized yet, or not.
isVerificationCodeValidForUser()	Returns whether a verification code is valid for the given user.
onActivateUser()	Fires an 'onActivateUser' event.
onBeforeActivateUser()	Fires an 'onBeforeActivateUser' event.
onBeforeDeleteUser()	Fires an 'onBeforeDeleteUser' event.
onBeforeSaveUser()	Fires an 'onBeforeSaveUser' event.
onBeforeSetPassword()	Fires an 'onBeforeSetPassword' event.
onBeforeSuspendUser()	Fires an 'onBeforeSuspendUser' event.
onBeforeUnlockUser()	Fires an 'onBeforeUnlockUser' event.
onBeforeUnsuspendUser()	Fires an 'onBeforeUnsuspendUser' event.
onBeforeVerifyUser()	Fires an 'onBeforeVerifyUser' event.
onDeleteUser()	Fires an 'onDeleteUser' event.
onLockUser()	Fires an 'onLockUser' event.
onSaveProfile()	Fires an 'onSaveProfile' event.
onSaveUser()	Fires an 'onSaveUser' event.
onSetPassword()	Fires an 'onSetPassword' event.
onSuspendUser()	Fires an 'onSuspendUser' event.
onUnlockUser()	Fires an 'onUnlockUser' event.
onUnsuspendUser()	Fires an 'onUnsuspendUser' event.
onVerifyUser()	Fires an 'onVerifyUser' event.
purgeExpiredPendingUsers()	Deletes any pending users that have shown zero sense of urgency and are just taking up space.
raiseEvent() (opens new window)	Raises an event.
saveProfile()	Saves a user's profile.
saveUser()	Saves a new or existing user.
saveUserPhoto()	Crops and saves a user’s photo.
sendActivationEmail()	Sends a new account activation email for a user, regardless of their status.
sendForgotPasswordEmail()	Sends a password reset email.
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.
unlockUser()	Unlocks a user, bypassing the cooldown phase.
unshunMessageForUser()	Un-shuns a message for a user.
unsuspendUser()	Unsuspends a user.
updateUserLoginInfo()	Updates a user's record for a successful login.
validatePassword()	Validates a given password against a hash.
verifyEmailForUser()	If 'unverifiedEmail' is set on the UserModel, 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\UserModel) – The user.

Returns

boolean (opens new window) – Whether the user was activated successfully.

Throws

• CDbException (opens new window)
• Exception (opens new window)

Signature

public boolean activateUser ( Craft\UserModel $user )

changePassword()

Changes a user’s password.

View source (opens new window)

Arguments

• $user (Craft\UserModel) – The user.
• $forceDifferent (boolean (opens new window)) – Whether to force the new password to be different than any existing password.

Returns

boolean (opens new window) – Whether the user’s new password was saved successfully.

Signature

public boolean changePassword ( Craft\UserModel $user, $forceDifferent = false )

deleteUser()

Deletes a user.

View source (opens new window)

Arguments

• $user (Craft\UserModel) – The user to be deleted.
• $transferContentTo (Craft\UserModel, null (opens new window)) – The user who should take over the deleted user’s content.

Returns

boolean (opens new window) – Whether the user was deleted successfully.

Throws

• Exception (opens new window)

Signature

public boolean deleteUser ( Craft\UserModel $user, Craft\UserModel $transferContentTo = null )

deleteUserPhoto()

Deletes a user's photo.

View source (opens new window)

Arguments

• $user (Craft\UserModel) – The user.

Returns

null (opens new window)

Signature

public null deleteUserPhoto ( Craft\UserModel $user )

getClient()

Returns the “Client” user account, if it has been created yet. An exception will be thrown if this function is called from Craft Personal or Pro.

if (craft()->getEdition() == Craft::Client)
{
    $clientAccount = craft()->users->getClient();
}

View source (opens new window)

Returns

Craft\UserModel, null (opens new window) – The “Client” user account, or null if it hasn’t been created yet.

Signature

public Craft\UserModel, null getClient ( )

getEmailVerifyUrl()

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

View source (opens new window)

Arguments

• $user (Craft\UserModel) – The user that should get the new Email Verification URL.

Returns

string (opens new window) – The new Email Verification URL.

Signature

public string getEmailVerifyUrl ( Craft\UserModel $user )

getPasswordResetUrl()

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

View source (opens new window)

Arguments

• $user (Craft\UserModel) – The user that should get the new Password Reset URL

Returns

string (opens new window) – The new Password Reset URL.

Signature

public string getPasswordResetUrl ( Craft\UserModel $user )

getUserByEmail()

Returns a user by their email.

$user = craft()->users->getUserByEmail($email);

View source (opens new window)

Arguments

• $email (string (opens new window)) – The user’s email.

Returns

Craft\UserModel, null (opens new window) – The user with the given email, or null if a user could not be found.

Signature

public Craft\UserModel, null getUserByEmail ( $email )

getUserById()

Returns a user by their ID.

$user = craft()->users->getUserById($userId);

View source (opens new window)

Arguments

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

Returns

Craft\UserModel, null (opens new window) – The user with the given ID, or null if a user could not be found.

Signature

public Craft\UserModel, null getUserById ( $userId )

getUserByUid()

Returns a user by their UID.

$user = craft()->users->getUserByUid($userUid);

View source (opens new window)

Arguments

• $uid (integer (opens new window)) – The user’s UID.

Returns

Craft\UserModel, null (opens new window) – The user with the given UID, or null if a user could not be found.

Signature

public Craft\UserModel, null getUserByUid ( $uid )

getUserByUsernameOrEmail()

Returns a user by their username or email.

$user = craft()->users->getUserByUsernameOrEmail($loginName);

View source (opens new window)

Arguments

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

Returns

Craft\UserModel, null (opens new window) – The user with the given username/email, or null if a user could not be found.

Signature

public Craft\UserModel, null getUserByUsernameOrEmail ( $usernameOrEmail )

handleInvalidLogin()

Handles an invalid login for a user.

View source (opens new window)

Arguments

• $user (Craft\UserModel) – The user.

Returns

boolean (opens new window) – Whether the user’s record was updated successfully.

Signature

public boolean handleInvalidLogin ( Craft\UserModel $user )

handleSuccessfulLogin()

DEPRECATED

Deprecated Deprecated in 2.3. Use {@link UsersService::updateUserLoginInfo() craft()->users->updateUserLoginInfo()} and {@link UserSessionService::storeSessionToken() craft()->userSession->storeSessionToken()} instead.

Handles a successful login for a user.

View source (opens new window)

Arguments

• $user (Craft\UserModel) – The user.
• $sessionToken (string (opens new window)) – The session token.

Returns

string (opens new window) – The session’s UID.

Signature

public string handleSuccessfulLogin ( Craft\UserModel $user, $sessionToken )

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.

Signature

public boolean hasUserShunnedMessage ( $userId, $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 (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\UserModel) – 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.

Signature

public boolean isVerificationCodeValidForUser ( Craft\UserModel $user, $code )

onActivateUser()

Fires an 'onActivateUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onActivateUser ( Craft\Event $event )

onBeforeActivateUser()

Fires an 'onBeforeActivateUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onBeforeActivateUser ( Craft\Event $event )

onBeforeDeleteUser()

Fires an 'onBeforeDeleteUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onBeforeDeleteUser ( Craft\Event $event )

onBeforeSaveUser()

Fires an 'onBeforeSaveUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onBeforeSaveUser ( Craft\Event $event )

onBeforeSetPassword()

Fires an 'onBeforeSetPassword' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onBeforeSetPassword ( Craft\Event $event )

onBeforeSuspendUser()

Fires an 'onBeforeSuspendUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onBeforeSuspendUser ( Craft\Event $event )

onBeforeUnlockUser()

Fires an 'onBeforeUnlockUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onBeforeUnlockUser ( Craft\Event $event )

onBeforeUnsuspendUser()

Fires an 'onBeforeUnsuspendUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onBeforeUnsuspendUser ( Craft\Event $event )

onBeforeVerifyUser()

Fires an 'onBeforeVerifyUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onBeforeVerifyUser ( Craft\Event $event )

onDeleteUser()

Fires an 'onDeleteUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onDeleteUser ( Craft\Event $event )

onLockUser()

Fires an 'onLockUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onLockUser ( Craft\Event $event )

onSaveProfile()

DEPRECATED

Deprecated Deprecated in 2.0. Use {@link onSaveUser() users.onSaveUser} instead.

Fires an 'onSaveProfile' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onSaveProfile ( Craft\Event $event )

onSaveUser()

Fires an 'onSaveUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onSaveUser ( Craft\Event $event )

onSetPassword()

Fires an 'onSetPassword' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onSetPassword ( Craft\Event $event )

onSuspendUser()

Fires an 'onSuspendUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onSuspendUser ( Craft\Event $event )

onUnlockUser()

Fires an 'onUnlockUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onUnlockUser ( Craft\Event $event )

onUnsuspendUser()

Fires an 'onUnsuspendUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onUnsuspendUser ( Craft\Event $event )

onVerifyUser()

Fires an 'onVerifyUser' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onVerifyUser ( Craft\Event $event )

purgeExpiredPendingUsers()

Deletes any pending users that have shown zero sense of urgency and are just taking up space. This method will check the 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)

Returns

null (opens new window)

Signature

public null purgeExpiredPendingUsers ( )

saveProfile()

DEPRECATED

Deprecated Deprecated in 2.0. Use {@link saveUser()} instead.

Saves a user's profile.

View source (opens new window)

Arguments

• $user (Craft\UserModel)

Returns

boolean (opens new window)

Signature

public boolean saveProfile ( Craft\UserModel $user )

saveUser()

Saves a new or existing user.

$user = new UserModel();
$user->username  = 'tommy';
$user->firstName = 'Tom';
$user->lastName  = 'Foolery';
$user->email     = 'tom@thefoolery.com';

$user->getContent()->birthYear = 1812;

$success = craft()->users->saveUser($user);

if (!$success)
{
    Craft::log('Couldn’t save the user "'.$user->username.'"', LogLevel::Error);
}

View source (opens new window)

Arguments

• $user (Craft\UserModel) – The user to be saved.

Returns

boolean (opens new window) – Whether the user was saved successfully.

Throws

• Exception (opens new window)

Signature

public boolean saveUser ( Craft\UserModel $user )

saveUserPhoto()

Crops and saves a user’s photo.

View source (opens new window)

Arguments

• $fileName (string (opens new window)) – The name of the file.
• $image (Craft\BaseImage) – The image.
• $user (Craft\UserModel) – The user.

Returns

boolean (opens new window) – Whether the photo was saved successfully.

Throws

• Exception (opens new window)

Signature

public boolean saveUserPhoto ( $fileName, Craft\BaseImage $image, Craft\UserModel $user )

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\UserModel) – The user to send the activation email to.

Returns

boolean (opens new window) – Whether the email was sent successfully.

Signature

public boolean sendActivationEmail ( Craft\UserModel $user )

sendForgotPasswordEmail()

DEPRECATED

Deprecated Deprecated in 2.3. Use {@link sendPasswordResetEmail()} instead.

Sends a password reset email.

View source (opens new window)

Arguments

• $user (Craft\UserModel) – The user to send the forgot password email to.

Returns

boolean (opens new window) – Whether the email was sent successfully.

Signature

public boolean sendForgotPasswordEmail ( Craft\UserModel $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 (opens new window)

Arguments

• $user (Craft\UserModel) – The user to send the activation email to.

Returns

boolean (opens new window) – Whether the email was sent successfully.

Signature

public boolean sendNewEmailVerifyEmail ( Craft\UserModel $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 (opens new window)

Arguments

• $user (Craft\UserModel) – The user to send the forgot password email to.

Returns

boolean (opens new window) – Whether the email was sent successfully.

Signature

public boolean sendPasswordResetEmail ( Craft\UserModel $user )

setVerificationCodeOnUser()

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

View source (opens new window)

Arguments

• $user (Craft\UserModel) – The user.

Returns

string (opens new window) – The user’s brand new verification code.

Signature

public string setVerificationCodeOnUser ( Craft\UserModel $user )

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 (Craft\DateTime) – When the message should be un-shunned. Defaults to null (never un-shun).

Returns

boolean (opens new window) – Whether the message was shunned successfully.

Signature

public boolean shunMessageForUser ( $userId, $message, $expiryDate = null )

suspendUser()

Suspends a user.

View source (opens new window)

Arguments

• $user (Craft\UserModel) – The user.

Returns

boolean (opens new window) – Whether the user was suspended successfully.

Throws

• CDbException (opens new window)
• Exception (opens new window)

Signature

public boolean suspendUser ( Craft\UserModel $user )

unlockUser()

Unlocks a user, bypassing the cooldown phase.

View source (opens new window)

Arguments

• $user (Craft\UserModel) – The user.

Returns

boolean (opens new window) – Whether the user was unlocked successfully.

Throws

• CDbException (opens new window)
• Exception (opens new window)

Signature

public boolean unlockUser ( Craft\UserModel $user )

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.

Signature

public boolean unshunMessageForUser ( $userId, $message )

unsuspendUser()

Unsuspends a user.

View source (opens new window)

Arguments

• $user (Craft\UserModel) – The user.

Returns

boolean (opens new window) – Whether the user was unsuspended successfully.

Throws

• CDbException (opens new window)
• Exception (opens new window)

Signature

public boolean unsuspendUser ( Craft\UserModel $user )

updateUserLoginInfo()

Updates a user's record for a successful login.

View source (opens new window)

Arguments

• $user (Craft\UserModel)

Returns

boolean (opens new window)

Throws

• Craft\Exception

Signature

public boolean updateUserLoginInfo ( Craft\UserModel $user )

validatePassword()

Validates a given password against a hash.

View source (opens new window)

Arguments

• $hash (string (opens new window)) – The hashed password.
• $password (string (opens new window)) – The submitted password.

Returns

boolean (opens new window) – Whether the submitted password matches the hashed password.

Signature

public boolean validatePassword ( $hash, $password )

verifyEmailForUser()

If 'unverifiedEmail' is set on the UserModel, then this method will transfer it to the official email property and clear the unverified one.

View source (opens new window)

Arguments

• $user (Craft\UserModel)

Returns

boolean (opens new window)

Throws

• Craft\Exception

Signature

public boolean verifyEmailForUser ( Craft\UserModel $user )