Events Reference

Craft provides several events that alert plugins when things are happening.

See Hooks and Events for an explanation of how events work in Craft, and how they differ from hooks.

# General Events

# onEditionChange

Raised by
Craft\AppBehavior::setEdition() (opens new window)

Raised after Craft’s edition changes.

# Params:

  • edition – The new edition (0 for Solo, 2 for Pro)

# db.onBackup

Raised by
Craft\DbConnection::backup() (opens new window)

Raised after a database backup has been created.

# Params:

  • filePath – The path to the new backup file.

# email.onBeforeSendEmail

Raised by
Craft\EmailService::sendEmail() (opens new window), Craft\EmailService::sendEmailByKey() (opens new window)

Raised right before an email is sent.

# Params:

Event handlers can prevent the email from getting sent by setting $event->performAction (opens new window) to false.

# email.onSendEmail

Raised by
Craft\EmailService::sendEmail() (opens new window), Craft\EmailService::sendEmailByKey() (opens new window)

Raised when an email is sent.

# Params:

# email.onSendEmailError

Raised by
Craft\EmailService::sendEmail() (opens new window), Craft\EmailService::sendEmailByKey() (opens new window)

Raised when an email fails to send.

# Params:

# i18n.onAddLocale

Raised by
Craft\LocalizationService::addSiteLocale() (opens new window)

Raised when a new locale is added to the site.

# Params:

  • localeId – The ID of the locale that was just added.

# i18n.onBeforeDeleteLocale

Raised by
Craft\LocalizationService::deleteSiteLocale() (opens new window)

Raised right before a locale is deleted.

# Params:

  • localeId – The ID of the locale that’s about to be deleted.
  • transferContentTo – The ID of the locale that the deleted locale’s content should be transferred to, if any.

Event handlers can prevent the locale from getting deleted by setting $event->performAction (opens new window) to false.

# localization.onDeleteLocale

Raised by
Craft\LocalizationService::deleteSiteLocale() (opens new window)

Raised when a locale is deleted.

# Params:

  • localeId – The ID of the locale that was deleted.
  • transferContentTo – The ID of the locale that the deleted locale’s content should have be transferred to, if any.

# plugins.onLoadPlugins

Raised by
Craft\PluginsService::loadPlugins() (opens new window)

Raised when Craft has finished loading all the plugins.

# updates.onBeginUpdate

Raised by
Craft\UpdatesService::prepareUpdate() (opens new window)

Raised when an update is beginning.

# Params:

  • type – A string either set to 'auto' or 'manual' indicating if the update is a manual update or auto-update.

# updates.onEndUpdate

Raised by
Craft\UpdatesService::updateCleanUp() (opens new window)

Raised when an update has ended.

# Params:

  • success – Set to true or false indicating if the update was successful or not.

# Element API Events

# content.onSaveContent

Raised by
Craft\ContentService::saveContent() (opens new window)

Raised when any element’s content is saved.

# Params:

# elements.onBeforeBuildElementsQuery

Raised by
Craft\ElementsService::buildElementsQuery() (opens new window)

Raised before Craft builds out an elements query, enabling plugins to modify the query or prevent it from actually happening.

# Params:

Event handlers can prevent the element query from being executed by setting $event->performAction (opens new window) to false.

# elements.onBuildElementsQuery

Raised by
Craft\ElementsService::buildElementsQuery() (opens new window)

Raised after Craft has built out an elements query, enabling plugins to modify the query.

# Params:

# elements.onBeforeDeleteElements

Raised by
Craft\ElementsService::deleteElementById() (opens new window)

Raised right before any elements are about to be deleted.

# Params:

  • elementIds – The element IDs that are about to be deleted.

# elements.onMergeElements

Raised by
Craft\ElementsService::mergeElementsByIds() (opens new window)

Raised when any element merged with another element.

# Params:

  • mergedElementId – The id of the element being merged.
  • prevailingElementId – The id of the element that prevailed in the merge.

# structures.onBeforeMoveElement

Raised by
Craft\StructuresService::prepend() (opens new window), Craft\StructuresService::append() (opens new window), Craft\StructuresService::prependToRoot() (opens new window), Craft\StructuresService::appendToRoot() (opens new window), Craft\StructuresService::moveBefore() (opens new window), Craft\StructuresService::moveAfter() (opens new window)

Raised right before an element is moved within a structure.

# Params:

Event handlers can prevent the element from getting moved by setting $event->performAction (opens new window) to false.

# structures.onMoveElement

Raised by
Craft\StructuresService::prepend() (opens new window), Craft\StructuresService::append() (opens new window), Craft\StructuresService::prependToRoot() (opens new window), Craft\StructuresService::appendToRoot() (opens new window), Craft\StructuresService::moveBefore() (opens new window), Craft\StructuresService::moveAfter() (opens new window)

Raised when an element is moved within a structure.

# Params:

# elements.onBeforePerformAction

Raised by
Craft\ElementIndexController::actionPerformAction() (opens new window)

Raised before a batch element action gets triggered.

# Params:

  • action – The element action class that is going to be performing the action.
  • criteria – The Craft\ElementCriteriaModel (opens new window) object that defines which element(s.html) the user has chosen to perform the action on.

Event handlers can prevent the element action from being triggered by setting $event->performAction (opens new window) to false.

# elements.onPerformAction

Raised by
Craft\ElementIndexController::actionPerformAction() (opens new window)

Raised after a batch element action has been performed.

# Params:

# elements.onPopulateElement

Raised by
Craft\ElementsService::findElements() (opens new window)

Raised when any element model is populated from its database result.

# Params:

  • element – The populated element.
  • result – The raw data representing the element from the database.

# elements.onPopulateElements

Raised by
Craft\ElementsService::populateElements() (opens new window)

Raised when all of the element models have been populated from an element query.

# Params:

  • elements – An array of the populated elements.
  • criteria – The ElementCriteriaModel that was used to define the element query.

# elements.onBeforeSaveElement

Raised by
Craft\ElementsService::saveElement() (opens new window)

Raised right before an element is saved.

# Params:

Event handlers can prevent the element from getting saved by setting $event->performAction (opens new window) to false.

# elements.onSaveElement

Raised by
Craft\ElementsService::saveElement() (opens new window)

Raised when an element is saved.

# Params:

# fields.onSaveFieldLayout

Raised by
Craft\FieldsService::saveLayout() (opens new window)

Raised when a field layout is saved.

# Params:

# Entry API Events

# entries.onBeforeSaveEntry

Raised by
Craft\EntriesService::saveEntry() (opens new window)

Raised right before an entry is saved.

# Params:

  • entry – An Craft\EntryModel (opens new window) object representing the entry that is about to be saved.
  • isNewEntry – A boolean indicating whether this is a brand new entry.

Event handlers can prevent the entry from getting saved by setting $event->performAction (opens new window) to false.

# entries.onSaveEntry

Raised by
Craft\EntriesService::saveEntry() (opens new window)

Raised when an entry is saved.

# Params:

# entries.onBeforeDeleteEntry

Raised by
Craft\EntriesService::deleteEntry() (opens new window)

Raised right before an entry is deleted.

# Params:

Event handlers can prevent the entry from being deleted by setting $event->performAction (opens new window) to false.

# entries.onDeleteEntry

Raised by
Craft\EntriesService::deleteEntry() (opens new window)

Raised when an entry is deleted.

# Params:

# entryRevisions.onSaveDraft

Raised by
Craft\EntryRevisionsService::saveDraft() (opens new window)

Raised right before a draft is saved.

# Params:

# entryRevisions.onPublishDraft

Raised by
Craft\EntryRevisionsService::publishDraft() (opens new window)

Raised when an draft is published.

# Params:

# entryRevisions.onBeforeDeleteDraft

Raised by
Craft\EntryRevisionsService::deleteDraft() (opens new window)

Raised right before a draft is deleted.

# Params:

Event handlers can prevent the draft from getting deleted by setting $event->performAction (opens new window) to false.

# entryRevisions.onDeleteDraft

Raised by
Craft\EntryRevisionsService::deleteDraft() (opens new window)

Raised right after a draft is deleted.

# Params:

# sections.onBeforeDeleteSection

Raised by
Craft\SectionsService::deleteSectionById() (opens new window)

Raised right before a section is deleted.

# Params:

  • sectionId – The ID of the section that is about to be deleted.

Event handlers can prevent the section from being deleted by setting $event->performAction (opens new window) to false.

# sections.onDeleteSection

Raised by
Craft\SectionsService::deleteSectionById() (opens new window)

Raised after a section is deleted.

# Params:

  • sectionId – The ID of the section that was just deleted.

# sections.onBeforeSaveEntryType

Raised by
Craft\SectionsService::saveEntryType() (opens new window)

Raised right before an entry type is saved.

# Params:

  • entryType – An Craft\EntryTypeModel (opens new window) object representing the entry type that is about to be saved.
  • isNewEntryType – A boolean indicating whether this is a brand new entry type.

Event handlers can prevent the entry type from getting saved by setting $event->performAction (opens new window) to false.

# sections.onSaveEntryType

Raised by
Craft\SectionsService::saveEntryType() (opens new window)

Raised when an entry type is saved.

# Params:

# sections.onBeforeSaveSection

Raised by
Craft\SectionsService::saveSection() (opens new window)

Raised right before a section is saved.

# Params:

  • section – An Craft\SectionModel (opens new window) object representing the section that is about to be saved.
  • isNewSection – A boolean indicating whether this is a brand new section.

Event handlers can prevent the section from getting saved by setting $event->performAction (opens new window) to false.

# sections.onSaveSection

Raised by
Craft\SectionsService::saveSection() (opens new window)

Raised when a section is saved.

# Params:

# Category API Events

# categories.onBeforeSaveCategory

Raised by
Craft\CategoriesService::saveCategory() (opens new window)

Raised before any category is saved.

# Params:

Event handlers can prevent the category from getting saved by setting $event->performAction (opens new window) to false.

# categories.onSaveCategory

Raised by
Craft\CategoriesService::saveCategory() (opens new window)

Raised when any category is saved.

# Params:

# categories.onBeforeDeleteCategory

Raised by
Craft\CategoriesService::deleteCategory() (opens new window)

Raised before any category is deleted.

# Params:

# categories.onDeleteCategory

Raised by
Craft\CategoriesService::deleteCategory() (opens new window)

Raised when any category is deleted.

# Params:

# categories.onBeforeDeleteGroup

Raised by
Craft\CategoriesService::deleteGroupById() (opens new window)

Raised before a category group is deleted.

# Params:

  • groupId – The ID of the category group that’s about to be deleted.

Event handlers can prevent the category group from being deleted by setting $event->performAction (opens new window) to false.

# categories.onDeleteGroup

Raised by
Craft\CategoriesService::deleteGroupById() (opens new window)

Raised after a category group is deleted.

# Params:

  • groupId – The ID of the category group that was just deleted.

# Tag API Events

# tags.onBeforeSaveTag

Raised by
Craft\TagsService::saveTag() (opens new window)

Raised when a tag is able to be saved.

# Params:

  • tag – A Craft\TagModel (opens new window) object representing the tag that is about to be saved.
  • isNewTag – A boolean indicating whether this is a brand new tag.

Event handlers can prevent the tag from getting saved by setting $event->performAction (opens new window) to false.

# tags.onSaveTag

Raised by
Craft\TagsService::saveTag() (opens new window)

Raised when a tag is saved.

# Params:

# Asset API Events

# assets.onBeforeDeleteAsset

Raised by
Craft\AssetsService::deleteFiles() (opens new window)

Raised right before an asset is deleted.

# Params:

# assets.onDeleteAsset

Raised by
Craft\AssetsService::deleteFiles() (opens new window)

Raised when an asset is deleted.

# Params:

# assets.onBeforeReplaceFile

Raised by
Craft\AssetsController::actionReplaceFile() (opens new window)

Raised right before an asset’s file is replaced.

# Params:

Event handlers can prevent the file from getting replaced by setting $event->performAction (opens new window) to false.

# assets.onReplaceFile

Raised by
Craft\AssetsController::actionReplaceFile() (opens new window)

Raised when any asset’s file is replaced.

# Params:

# assets.onBeforeSaveAsset

Raised by
Craft\AssetsService::storeFile() (opens new window)

Raised right before an asset is saved.

# Params:

Event handlers can prevent the asset from getting saved by setting $event->performAction (opens new window) to false.

# assets.onSaveAsset

Raised by
Craft\AssetsService::storeFile() (opens new window)

Raised when any asset is saved.

# Params:

# assets.onBeforeUploadAsset

Raised by
Craft\BaseAssetSourceType::insertFileByPath() (opens new window)

Raised right before an asset is uploaded to its source.

# Params:

  • path – The path to the temporary file on the server.
  • folder – An Craft\AssetFolderModel (opens new window) object representing the asset folder that the file is going to be saved to.
  • filename – The filename of the file.

Event handlers can prevent the asset from getting uploaded by setting $event->performAction (opens new window) to false.

# Global Set API Events

# globals.onBeforeSaveGlobalContent

Raised by
Craft\GlobalsService::saveContent() (opens new window)

Raised right before a Global Set’s content is saved.

# Params:

Event handlers can prevent the global set from getting saved by setting $event->performAction (opens new window) to false.

# globals.onSaveGlobalContent

Raised by
Craft\GlobalsService::saveContent() (opens new window)

Raised when a Global Set’s content is saved.

# Params:

# User API Events

# userSession.onBeforeLogin

Raised by
Craft\UserSessionService::login() (opens new window)

Raised right before a user is logged in.

# Params:

  • username – A string of the username that is about to log in.

Event handlers can prevent the user from getting logged in by setting $event->performAction (opens new window) to false.

# userSession.onLogin

Raised by
Craft\UserSessionService::login() (opens new window)

Raised when a user has logged in.

# Params:

  • username – A string of the username that has just logged in.

# userSession.onBeforeLogout

Raised by
Craft\UserSessionService::beforeLogout() (opens new window)

Raised right before a user is logged out.

# Params:

Event handlers can prevent the user from getting logged out by setting $event->performAction (opens new window) to false.

# userSession.onLogout

Raised by
Craft\UserSessionService::afterLogout() (opens new window)

Raised when a user is logged out.

# users.onBeforeActivateUser

Raised by
Craft\UsersService::activateUser() (opens new window)

Raised right before a user is activated.

# Params:

Event handlers can prevent the user from getting activated by setting $event->performAction (opens new window) to false.

# users.onActivateUser

Raised by
Craft\UsersService::activateUser() (opens new window)

Raised when a user is activated.

# Params:

# userGroups.onBeforeAssignUserToGroups

Raised by
Craft\UserGroupsService::assignUserToGroups (opens new window)

Raised right before a user’s group assignments are updated. Note that this could be called even if the group assignments haven’t changed.

# Params:

  • userId – The ID of the user whose group assignments are about to be updated.
  • groupIds – The user’s new group IDs (if any).

Event handlers can prevent the user’s new group assignments from getting saved by setting $event->performAction (opens new window) to false.

# userGroups.onAssignUserToGroups

Raised by
Craft\UserGroupsService::assignUserToGroups (opens new window)

Raised right after a user’s group assignments are updated.

# Params:

  • userId – The ID of the user whose group assignments were updated.
  • groupIds – The user’s new group IDs (if any).

# users.onBeforeDeleteUser

Raised by
Craft\UsersService::deleteUser() (opens new window)

Raised right before a user is deleted.

# Params:

Event handlers can prevent the user from getting deleted by setting $event->performAction (opens new window) to false.

# users.onDeleteUser

Raised by
Craft\UsersService::deleteUser() (opens new window)

Raised when a user is deleted.

# Params:

# users.onBeforeSaveUser

Raised by
Craft\UsersService::saveUser() (opens new window)

Raised right before a user is saved.

# Params:

  • user – A Craft\UserModel (opens new window) object representing the user that’s about to be saved.
  • isNewUser – A boolean indicating whether this is a brand new user account.

Event handlers can prevent the user from getting saved by setting $event->performAction (opens new window) to false.

# users.onSaveUser

Raised by
Craft\UsersService::saveUser() (opens new window)

Raised when a user is saved.

# Params:

  • user – A Craft\UserModel (opens new window) object representing the user that was just saved.
  • isNewUser – A boolean indicating whether this is a brand new user account.

# users.onBeforeSetPassword

Raised by
Craft\UsersService::saveUser() (opens new window), Craft\UsersService::changePassword() (opens new window)

Raised right before a user’s password is changed.

# Params:

Event handlers can prevent the user’s password from getting changed by setting $event->performAction (opens new window) to false.

# users.onSetPassword

Raised by
Craft\UsersService::saveUser() (opens new window), Craft\UsersService::changePassword() (opens new window)

Raised when a user’s password is changed.

# Params:

# users.onBeforeSuspendUser

Raised by
Craft\UsersService::suspendUser() (opens new window)

Raised right before a user is suspended.

# Params:

Event handlers can prevent the user from getting suspended by setting $event->performAction (opens new window) to false.

# users.onSuspendUser

Raised by
Craft\UsersService::suspendUser() (opens new window)

Raised when a user is suspended.

# Params:

# users.onLockUser

Raised by
Craft\UsersService::lockUser() (opens new window)

Raised when a user is locked.

# Params:

# users.onBeforeUnlockUser

Raised by
Craft\UsersService::unlockUser() (opens new window)

Raised right before a user is unlocked.

# Params:

Event handlers can prevent the user from getting unlocked by setting $event->performAction (opens new window) to false.

# users.onUnlockUser

Raised by
Craft\UsersService::unlockUser() (opens new window)

Raised when a user is unlocked.

# Params:

# users.onBeforeUnsuspendUser

Raised by
Craft\UsersService::unsuspendUser() (opens new window)

Raised right before a user is unsuspended.

# Params:

Event handlers can prevent the user from getting unsuspended by setting $event->performAction (opens new window) to false.

# users.onUnsuspendUser

Raised by
Craft\UsersService::unsuspendUser() (opens new window)

Raised when a user is unsuspended.

# Params:

# users.onBeforeVerifyUser

Raised by
Craft\UsersController::actionSetPassword() (opens new window), Craft\UsersController::actionVerifyEmail() (opens new window)

Raised right before a user’s email is verified.

# Params:

# users.onVerifyUser

Raised by
Craft\UsersController::actionSetPassword() (opens new window), Craft\UsersController::actionVerifyEmail() (opens new window)

Raised when a user’s email is verified.

# Params:

# userGroups.onBeforeAssignUserToDefaultGroup

Raised by
Craft\UserGroupsService::assignUserToDefaultGroup() (opens new window)

Raised towards the end of a public user registration request before a user is assigned to a default user group.

# Params:

  • user – A Craft\UserModel (opens new window) object representing the user that was just registered.
  • defaultGroupId – The id of the user group that the user is about to be assigned to.

# userGroups.onAssignUserToDefaultGroup

Raised by
Craft\UserGroupsService::assignUserToDefaultGroup() (opens new window)

Raised towards the end of a public user registration request after a user is assigned to a default user group.

# Params:

  • user – A Craft\UserModel (opens new window) object representing the user that was just registered.
  • defaultGroupId – The id of the user group that the user was just assigned to.