Skip to content

Elements

Type
Class
Namespace
craft\services
Inherits
craft\services\Elements » yii\base\Component » yii\base\BaseObject
Implements
yii\base\Configurable
Since
3.0.0

The Elements service provides APIs for managing elements.

An instance of the service is available via Craft::$app->elements.

View source

Public Properties

PropertyDescription
allElementTypesstring[] – The available element classes.
behaviorsyii\base\Behavior – List of behaviors attached to this component.
bulkOpDbcraft\db\Connection, array, string – The DB connection object or the application component ID of the DB connection that should be used to store element bulk op records.
cacheExpiryDateDateTime
elementUricraft\base\ElementInterface
isCollectingCacheInfoboolean
isCollectingCacheTagsboolean
placeholderElementcraft\base\ElementInterface – The element currently being edited by Live Preview.
placeholderElementscraft\base\ElementInterface[]

allElementTypes

Type
string[]
Default value
null
Access
Read-only

The available element classes.

View source

bulkOpDb

Type
craft\db\Connection, array, string
Default value
'db2'
Since
5.3.0

The DB connection object or the application component ID of the DB connection that should be used to store element bulk op records.

View source

cacheExpiryDate

Type
DateTime
Default value
null
Access
Write-only
Since
4.3.0

View source

elementUri

Type
craft\base\ElementInterface
Default value
null
Access
Write-only
Since
4.6.0

View source

isCollectingCacheInfo

Type
boolean
Default value
null
Access
Read-only
Since
4.3.0

View source

isCollectingCacheTags

Type
boolean
Default value
null
Access
Read-only
Since
3.5.0

View source

placeholderElement

Type
craft\base\ElementInterface
Default value
null
Access
Write-only

The element currently being edited by Live Preview.

View source

placeholderElements

Type
craft\base\ElementInterface[]
Default value
null
Access
Read-only
Since
3.2.5

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.
attachBehavior()Attaches a behavior to this component.
attachBehaviors()Attaches a list of behaviors to the component.
beginBulkOp()Begins tracking element saves and deletes as part of a bulk operation, identified by a unique key.
behaviors()Returns a list of behaviors that this component should behave as.
canCreateDrafts()Returns whether a user is authorized to create drafts for the given element.
canDelete()Returns whether a user is authorized to delete the given element.
canDeleteForSite()Returns whether a user is authorized to delete the given element for its current site.
canDuplicate()Returns whether a user is authorized to duplicate the given element.
canDuplicateAsDraft()Returns whether a user is authorized to duplicate the given element as an unpublished draft.
canGetProperty()Returns a value indicating whether a property can be read.
canSave()Returns whether a user is authorized to save the given element in its current form.
canSetProperty()Returns a value indicating whether a property can be set.
canView()Returns whether a user is authorized to view the given element’s edit page.
className()Returns the fully qualified name of this class.
collectCacheInfoForElement()* Stores cache invalidation info for a given element.
collectCacheTags()Adds element cache invalidation tags to the current collection.
createAction()Creates an element action with a given config.
createEagerLoadingPlans()Normalizes a with element query param into an array of eager-loading plans.
createElement()Creates an element with a given config.
createElementQuery()Creates an element query for a given element type.
createExporter()Creates an element exporter with a given config.
deleteElement()Deletes an element.
deleteElementById()Deletes an element by its ID.
deleteElementForSite()Deletes an element in the site it’s loaded in.
deleteElementsForSite()Deletes elements in the site they are currently loaded in.
detachBehavior()Detaches a behavior from the component.
detachBehaviors()Detaches all behaviors from the component.
duplicateElement()Duplicates an element.
eagerLoadElements()Eager-loads additional elements onto a given set of elements.
endBulkOp()Finishes tracking element saves and deletes as part of a bulk operation.
ensureBehaviors()Makes sure that the behaviors declared in behaviors() are attached to this component.
ensureBulkOp()Ensures that we’re tracking element saves and deletes as part of a bulk operation, then executes the given callback function.
getAllElementTypes()Returns all available element classes.
getBehavior()Returns the named behavior object.
getBehaviors()Returns all behaviors attached to this component.
getElementById()Returns an element by its ID.
getElementByUid()Returns an element by its UID.
getElementByUri()Returns an element by its URI.
getElementTypeById()Returns the class of an element with a given ID.
getElementTypeByRefHandle()Returns an element class by its handle.
getElementTypeByUid()Returns the class of an element with a given UID.
getElementTypesByIds()Returns the classes of elements with the given IDs.
getElementUriForSite()Returns an element’s URI for a given site.
getEnabledSiteIdsForElement()Returns the site IDs that a given element is enabled in.
getIsCollectingCacheInfo()Returns whether we are currently collecting element cache invalidation info.
getIsCollectingCacheTags()Returns whether we are currently collecting element cache invalidation tags.
getPlaceholderElement()Returns a placeholder element by its ID and site ID.
getPlaceholderElements()Returns all placeholder elements.
getRecentActivity()Returns the recent activity for an element.
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.
init()Initializes the object.
invalidateAllCaches()Invalidates all element caches.
invalidateCachesForElement()Invalidates caches for the given element.
invalidateCachesForElementType()Invalidates caches for the given element type.
mergeCanonicalChanges()Merges recent canonical element changes into a given derivative, such as a draft.
mergeElements()Merges two elements together.
mergeElementsByIds()Merges two elements together by their IDs.
off()Detaches an existing event handler from this component.
on()Attaches an event handler to an event.
parseRefs()Parses a string for element reference tags.
propagateElement()Propagates an element to a different site.
propagateElements()Propagates all elements that match a given element query to another site(s).
resaveElements()Resaves all elements that match a given element query.
restoreElement()Restores an element.
restoreElements()Restores multiple elements.
resumeBulkOp()Resumes tracking element saves and deletes as part of a bulk operation.
saveElement()Handles all of the routine tasks that go along with saving elements.
setCacheExpiryDate()Sets a possible cache expiration date that stopCollectingCacheInfo() should return.
setElementUri()Sets the URI on an element.
setPlaceholderElement()Stores a placeholder element that element queries should use instead of populating a new element with a matching ID and site ID.
startCollectingCacheInfo()Starts collecting element cache invalidation info.
startCollectingCacheTags()Starts collecting element cache invalidation tags.
stopCollectingCacheInfo()Stops collecting element invalidation info, and returns a yii\caching\TagDependency and recommended max cache duration that should be used when saving the cache data.
stopCollectingCacheTags()Stops collecting element cache invalidation tags, and returns a cache dependency object.
trackActivity()Tracks new activity for an element.
trackElementInBulkOps()Tracks an element as being affected by any active bulk operations.
trigger()Triggers an event.
updateCanonicalElement()Updates the canonical element from a given derivative, such as a draft or revision.
updateDescendantSlugsAndUris()Updates an element’s descendants’ slugs and URIs.
updateElementSlugAndUri()Updates an element’s slug and URI, along with any descendants.
updateElementSlugAndUriInOtherSites()Updates an element’s slug and URI, for any sites besides the given one.

beginBulkOp()

Since
5.0.0

Begins tracking element saves and deletes as part of a bulk operation, identified by a unique key.

View source

Returns

string – The bulk operation key

canCreateDrafts()

Since
4.3.0

Returns whether a user is authorized to create drafts for the given element.

This should always be called in conjunction with canView() or canSave().

View source

Arguments

Returns

boolean

canDelete()

Since
4.3.0

Returns whether a user is authorized to delete the given element.

This should always be called in conjunction with canView() or canSave().

View source

Arguments

Returns

boolean

canDeleteForSite()

Since
4.3.0

Returns whether a user is authorized to delete the given element for its current site.

This should always be called in conjunction with canView() or canSave().

View source

Arguments

Returns

boolean

canDuplicate()

Since
4.3.0

Returns whether a user is authorized to duplicate the given element.

This should always be called in conjunction with canView() or canSave().

View source

Arguments

Returns

boolean

canDuplicateAsDraft()

Since
5.0.0

Returns whether a user is authorized to duplicate the given element as an unpublished draft.

View source

Arguments

Returns

boolean

canSave()

Since
4.3.0

Returns whether a user is authorized to save the given element in its current form.

View source

Arguments

Returns

boolean

canView()

Since
4.3.0

Returns whether a user is authorized to view the given element’s edit page.

View source

Arguments

Returns

boolean

collectCacheInfoForElement()

Since
4.5.0
  • Stores cache invalidation info for a given element.

View source

Arguments

collectCacheTags()

Since
3.5.0

Adds element cache invalidation tags to the current collection.

View source

Arguments

createAction()

Creates an element action with a given config.

View source

Arguments

  • $config (string, array) – The element action’s class name, or its config, with a type value and optionally a settings value

Returns

\craft\services\T – The element action

createEagerLoadingPlans()

Since
3.5.0

Normalizes a with element query param into an array of eager-loading plans.

View source

Arguments

Returns

craft\elements\db\EagerLoadPlan[]

createElement()

Creates an element with a given config.

View source

Arguments

  • $config (string, array) – The element’s class name, or its config, with a type value

Returns

\craft\services\T – The element

createElementQuery()

Since
3.5.0

Creates an element query for a given element type.

View source

Arguments

  • $elementType (string) – The element class

Returns

craft\elements\db\ElementQueryInterface – The element query

Throws

createExporter()

Creates an element exporter with a given config.

View source

Arguments

  • $config (string, array) – The element exporter’s class name, or its config, with a type value and optionally a settings value

Returns

\craft\services\T – The element exporter

deleteElement()

Deletes an element.

View source

Arguments

  • $element (craft\base\ElementInterface) – The element to be deleted
  • $hardDelete (boolean) – Whether the element should be hard-deleted immediately, instead of soft-deleted

Returns

boolean – Whether the element was deleted successfully

Throws

deleteElementById()

Deletes an element by its ID.

View source

Arguments

  • $elementId (integer) – The element’s ID
  • $elementType (string, null) – The element class.
  • $siteId (integer, null) – The site to fetch the element in. Defaults to the current site.
  • $hardDelete (boolean) – Whether the element should be hard-deleted immediately, instead of soft-deleted

Returns

boolean – Whether the element was deleted successfully

Throws

deleteElementForSite()

Since
4.4.0

Deletes an element in the site it’s loaded in.

View source

Arguments

deleteElementsForSite()

Since
4.4.0

Deletes elements in the site they are currently loaded in.

View source

Arguments

Throws

duplicateElement()

Duplicates an element.

View source

Arguments

  • $element (\craft\services\T) – The element to duplicate
  • $newAttributes (array) – Any attributes to apply to the duplicate. This can contain a siteAttributes key, set to an array of site-specific attribute array, indexed by site IDs.
  • $placeInStructure (boolean) – Whether to position the cloned element after the original one in its structure. (This will only happen if the duplicated element is canonical.)
  • $asUnpublishedDraft (boolean) – Whether the duplicate should be created as unpublished draft

Returns

\craft\services\T – The duplicated element

Throws

eagerLoadElements()

Eager-loads additional elements onto a given set of elements.

View source

Arguments

endBulkOp()

Since
5.0.0

Finishes tracking element saves and deletes as part of a bulk operation.

View source

Arguments

ensureBulkOp()

Since
5.3.0

Ensures that we’re tracking element saves and deletes as part of a bulk operation, then executes the given callback function.

View source

Arguments

getAllElementTypes()

Returns all available element classes.

View source

Returns

string[] – The available element classes.

getElementById()

Returns an element by its ID.

If no element type is provided, the method will first have to run a DB query to determine what type of element the $id is, so you should definitely pass it if it’s known. The element’s status will not be a factor when using this method.

View source

Arguments

Returns

\craft\services\T, null – The matching element, or null.

getElementByUid()

Since
3.5.13

Returns an element by its UID.

If no element type is provided, the method will first have to run a DB query to determine what type of element the $uid is, so you should definitely pass it if it’s known. The element’s status will not be a factor when using this method.

View source

Arguments

Returns

\craft\services\T, null – The matching element, or null.

getElementByUri()

Returns an element by its URI.

View source

Arguments

  • $uri (string) – The element’s URI.
  • $siteId (integer, null) – The site to look for the URI in, and to return the element in. Defaults to the current site.
  • $enabledOnly (boolean) – Whether to only look for an enabled element. Defaults to false.

Returns

craft\base\ElementInterface, null – The matching element, or null.

getElementTypeById()

Returns the class of an element with a given ID.

View source

Arguments

  • $elementId (integer) – The element’s ID

Returns

string, null – The element’s class, or null if it could not be found

getElementTypeByRefHandle()

Returns an element class by its handle.

View source

Arguments

  • $refHandle (string) – The element class handle

Returns

string, null – The element class, or null if it could not be found

getElementTypeByUid()

Since
3.5.13

Returns the class of an element with a given UID.

View source

Arguments

  • $uid (string) – The element’s UID

Returns

string, null – The element’s class, or null if it could not be found

getElementTypesByIds()

Returns the classes of elements with the given IDs.

View source

Arguments

  • $elementIds (integer[]) – The elements’ IDs

Returns

string[]

getElementUriForSite()

Returns an element’s URI for a given site.

View source

Arguments

  • $elementId (integer) – The element’s ID.
  • $siteId (integer) – The site to search for the element’s URI in.

Returns

string, null, false – The element’s URI or null, or false if the element doesn’t exist.

getEnabledSiteIdsForElement()

Returns the site IDs that a given element is enabled in.

View source

Arguments

  • $elementId (integer) – The element’s ID.

Returns

integer[] – The site IDs that the element is enabled in. If the element could not be found, an empty array will be returned.

getIsCollectingCacheInfo()

Since
4.3.0

Returns whether we are currently collecting element cache invalidation info.

See also:

View source

Returns

boolean

getIsCollectingCacheTags()

DEPRECATED

Deprecated in 4.3.0. getIsCollectingCacheInfo() should be used instead.

Since
3.5.0

Returns whether we are currently collecting element cache invalidation tags.

View source

Returns

boolean

getPlaceholderElement()

Returns a placeholder element by its ID and site ID.

See also setPlaceholderElement()View source

Arguments

  • $sourceId (integer) – The element’s ID
  • $siteId (integer) – The element’s site ID

Returns

craft\base\ElementInterface, null – The placeholder element if one exists, or null.

getPlaceholderElements()

Since
3.2.5

Returns all placeholder elements.

View source

Returns

craft\base\ElementInterface[]

getRecentActivity()

Since
4.5.0

Returns the recent activity for an element.

View source

Arguments

Returns

craft\models\ElementActivity[]

init()

Initializes the object.

This method is invoked at the end of the constructor after the object is initialized with the given configuration.

View source

invalidateAllCaches()

Since
3.5.0

Invalidates all element caches.

View source

invalidateCachesForElement()

Since
3.5.0

Invalidates caches for the given element.

View source

Arguments

invalidateCachesForElementType()

Since
3.5.0

Invalidates caches for the given element type.

View source

Arguments

mergeCanonicalChanges()

Since
3.7.0

Merges recent canonical element changes into a given derivative, such as a draft.

View source

Arguments

mergeElements()

Since
3.1.31

Merges two elements together.

This method will update the following:

  • Any relations involving the merged element
  • Any structures that contain the merged element
  • Any reference tags in textual custom fields referencing the merged element

View source

Arguments

Returns

boolean – Whether the elements were merged successfully.

Throws

mergeElementsByIds()

Merges two elements together by their IDs.

This method will update the following:

  • Any relations involving the merged element
  • Any structures that contain the merged element
  • Any reference tags in textual custom fields referencing the merged element

View source

Arguments

  • $mergedElementId (integer) – The ID of the element that is going away.
  • $prevailingElementId (integer) – The ID of the element that is sticking around.

Returns

boolean – Whether the elements were merged successfully.

Throws

parseRefs()

Parses a string for element reference tags.

View source

Arguments

  • $str (string) – The string to parse
  • $defaultSiteId (integer, null) – The default site ID to query the elements in

Returns

string – The parsed string

propagateElement()

Since
3.0.13

Propagates an element to a different site.

View source

Arguments

Returns

craft\base\ElementInterface – The element in the target site

Throws

propagateElements()

Since
3.2.0

Propagates all elements that match a given element query to another site(s).

View source

Arguments

Throws

  • Throwable
    if reasons propagated to all supported sites, except the one they were queried in.

resaveElements()

Since
3.2.0

Resaves all elements that match a given element query.

View source

Arguments

  • $query (craft\elements\db\ElementQueryInterface) – The element query to fetch elements with
  • $continueOnError (boolean) – Whether to continue going if an error occurs
  • $skipRevisions (boolean) – Whether elements that are (or belong to) a revision should be skipped
  • $updateSearchIndex (boolean, null) – Whether to update the element search index for the element (this will happen via a background job if this is a web request)
  • $touch (boolean) – Whether to update the dateUpdated timestamps for the elements

Throws

restoreElement()

Since
3.1.0

Restores an element.

View source

Arguments

Returns

boolean – Whether the element was restored successfully

Throws

restoreElements()

Restores multiple elements.

View source

Arguments

Returns

boolean – Whether at least one element was restored successfully

Throws

resumeBulkOp()

Since
5.0.0

Resumes tracking element saves and deletes as part of a bulk operation.

View source

Arguments

saveElement()

Handles all of the routine tasks that go along with saving elements.

Those tasks include:

  • Validating its content (if $validateContent is true, or it’s left as null and the element is enabled)
  • Ensuring the element has a title if its type has titles, and giving it a default title in the event that $validateContent is set to false
  • Saving a row in the elements table
  • Assigning the element’s ID on the element model, if it’s a new element
  • Assigning the element’s ID on the element’s content model, if there is one and it’s a new set of content
  • Updating the search index with new keywords from the element’s content
  • Setting a unique URI on the element, if it’s supposed to have one.
  • Saving the element’s row(s) in the elements_sites and content tables
  • Deleting any rows in the elements_sites and content tables that no longer need to be there
  • Cleaning any template caches that the element was involved in

The function will fire beforeElementSave and afterElementSave events, and will call beforeSave() and afterSave() methods on the passed-in element, giving the element opportunities to hook into the save process.

Example usage - creating a new entry:

php
$entry = new Entry();
$entry->sectionId = 10;
$entry->typeId = 1;
$entry->authorId = 5;
$entry->enabled = true;
$entry->title = "Hello World!";
$entry->setFieldValues([
    'body' => "<p>I can’t believe I literally just called this “Hello World!”.</p>",
]);
$success = Craft::$app->elements->saveElement($entry);
if (!$success) {
    Craft::error('Couldn’t save the entry "'.$entry->title.'"', __METHOD__);
}

View source

Arguments

  • $element (craft\base\ElementInterface) – The element that is being saved
  • $runValidation (boolean) – Whether the element should be validated
  • $propagate (boolean) – Whether the element should be saved across all of its supported sites (this can only be disabled when updating an existing element)
  • $updateSearchIndex (boolean, null) – Whether to update the element search index for the element (this will happen via a background job if this is a web request)
  • $forceTouch (boolean) – Whether to force the dateUpdated timestamp to be updated for the element, regardless of whether it’s being resaved
  • $crossSiteValidate (boolean, null) – Whether the element should be validated across all supported sites
  • $saveContent (boolean) – Whether all the element’s content should be saved. When false (default) only dirty fields will be saved.

Returns

boolean

Throws

setCacheExpiryDate()

Since
4.3.0

Sets a possible cache expiration date that stopCollectingCacheInfo() should return.

The value will only be used if it is less than the currently stored expiration date.

View source

Arguments

setElementUri()

Since
4.6.0

Sets the URI on an element.

View source

Arguments

Throws

setPlaceholderElement()

Stores a placeholder element that element queries should use instead of populating a new element with a matching ID and site ID.

This is used by Live Preview and Sharing features.

See also getPlaceholderElement()View source

Arguments

Throws

startCollectingCacheInfo()

Since
4.3.0

Starts collecting element cache invalidation info.

View source

startCollectingCacheTags()

DEPRECATED

Deprecated in 4.3.0. startCollectingCacheInfo() should be used instead.

Since
3.5.0

Starts collecting element cache invalidation tags.

View source

stopCollectingCacheInfo()

Since
4.3.0

Stops collecting element invalidation info, and returns a yii\caching\TagDependency and recommended max cache duration that should be used when saving the cache data.

If no cache tags were registered, [null, null] will be returned.

View source

Returns

array

stopCollectingCacheTags()

DEPRECATED

Deprecated in 4.3.0. stopCollectingCacheInfo() should be used instead.

Since
3.5.0

Stops collecting element cache invalidation tags, and returns a cache dependency object.

View source

Returns

yii\caching\TagDependency

trackActivity()

Since
4.5.0

Tracks new activity for an element.

View source

Arguments

trackElementInBulkOps()

Since
5.0.0

Tracks an element as being affected by any active bulk operations.

View source

Arguments

updateCanonicalElement()

Since
3.7.0

Updates the canonical element from a given derivative, such as a draft or revision.

View source

Arguments

  • $element (\craft\services\T) – The derivative element
  • $newAttributes (array) – Any attributes to apply to the canonical element

Returns

\craft\services\T – The updated canonical element

Throws

updateDescendantSlugsAndUris()

Updates an element’s descendants’ slugs and URIs.

View source

Arguments

  • $element (craft\base\ElementInterface) – The element whose descendants should be updated.
  • $updateOtherSites (boolean) – Whether the element’s other sites should also be updated.
  • $queue (boolean) – Whether the descendants’ slugs and URIs should be updated via a job in the queue.

updateElementSlugAndUri()

Updates an element’s slug and URI, along with any descendants.

View source

Arguments

  • $element (craft\base\ElementInterface) – The element to update.
  • $updateOtherSites (boolean) – Whether the element’s other sites should also be updated.
  • $updateDescendants (boolean) – Whether the element’s descendants should also be updated.
  • $queue (boolean) – Whether the element’s slug and URI should be updated via a job in the queue.

Throws

updateElementSlugAndUriInOtherSites()

Updates an element’s slug and URI, for any sites besides the given one.

View source

Arguments

Events

EVENT_AFTER_BULK_OP

Type
craft\events\BulkOpEvent
Since
5.0.0

The event that is triggered after a bulk element operation is completed.

Note that this won’t necessarily fire from the same request as EVENT_BEFORE_BULK_OP.


EVENT_AFTER_DELETE_ELEMENT

Type
craft\events\ElementEvent

The event that is triggered after an element is deleted.


EVENT_AFTER_DELETE_FOR_SITE

Type
craft\events\ElementEvent
Since
4.4.0

The event that is triggered after deleting an element for a single site.

See also:


EVENT_AFTER_MERGE_CANONICAL_CHANGES

Type
craft\events\ElementEvent
Since
3.7.0

The event that is triggered after canonical element changes are merged into a derivative.


EVENT_AFTER_MERGE_ELEMENTS

Type
craft\events\MergeElementsEvent

The event that is triggered after two elements are merged together.


EVENT_AFTER_PERFORM_ACTION

Type
craft\events\ElementActionEvent

The event that is triggered after an element action is performed.


EVENT_AFTER_PROPAGATE_ELEMENT

Type
craft\events\MultiElementActionEvent

The event that is triggered after an element is propagated.


EVENT_AFTER_PROPAGATE_ELEMENTS

Type
craft\events\ElementQueryEvent

The event that is triggered after propagating a batch of elements.


EVENT_AFTER_RESAVE_ELEMENT

Type
craft\events\MultiElementActionEvent

The event that is triggered after an element is resaved.


EVENT_AFTER_RESAVE_ELEMENTS

Type
craft\events\ElementQueryEvent

The event that is triggered after resaving a batch of elements.


EVENT_AFTER_RESTORE_ELEMENT

Type
craft\events\ElementEvent
Since
3.1.0

The event that is triggered after an element is restored.


EVENT_AFTER_SAVE_ELEMENT

Type
craft\events\ElementEvent

The event that is triggered after an element is saved.

If you want to ignore events for drafts or revisions, call craft\helpers\ElementHelper::isDraftOrRevision() from your event handler:

php
use craft\events\ElementEvent;
use craft\helpers\ElementHelper;
use craft\services\Elements;

Craft::$app->elements->on(Elements::EVENT_AFTER_SAVE_ELEMENT, function(ElementEvent $e) {
    if (ElementHelper::isDraftOrRevision($e->element)) {
        return;
    }

    // ...
});

EVENT_AFTER_UPDATE_SLUG_AND_URI

Type
craft\events\ElementEvent

The event that is triggered after an element’s slug and URI are updated, usually following a Structure move.


EVENT_AUTHORIZE_CREATE_DRAFTS

Type
craft\events\AuthorizationCheckEvent
Since
4.3.0

The event that is triggered when determining whether a user is authorized to create drafts for an element.

To authorize the user, set craft\events\AuthorizationCheckEvent::$authorized to true.

php
use craft\events\AuthorizationCheckEvent;
use craft\services\Elements;
use yii\base\Event;

Event::on(
    Elements::class,
    Elements::EVENT_AUTHORIZE_CREATE_DRAFTS,
    function(AuthorizationCheckEvent $event) {
        $event->authorized = true;
    }
);

See also canCreateDrafts()


EVENT_AUTHORIZE_DELETE

Type
craft\events\AuthorizationCheckEvent
Since
4.3.0

The event that is triggered when determining whether a user is authorized to delete an element.

To authorize the user, set craft\events\AuthorizationCheckEvent::$authorized to true.

php
use craft\events\AuthorizationCheckEvent;
use craft\services\Elements;
use yii\base\Event;

Event::on(
    Elements::class,
    Elements::EVENT_AUTHORIZE_DELETE,
    function(AuthorizationCheckEvent $event) {
        $event->authorized = true;
    }
);

See also canDelete()


EVENT_AUTHORIZE_DELETE_FOR_SITE

Type
craft\events\AuthorizationCheckEvent
Since
4.3.0

The event that is triggered when determining whether a user is authorized to delete an element for its current site.

To authorize the user, set craft\events\AuthorizationCheckEvent::$authorized to true.

php
use craft\events\AuthorizationCheckEvent;
use craft\services\Elements;
use yii\base\Event;

Event::on(
    Elements::class,
    Elements::EVENT_AUTHORIZE_DELETE_FOR_SITE,
    function(AuthorizationCheckEvent $event) {
        $event->authorized = true;
    }
);

See also canDeleteForSite()


EVENT_AUTHORIZE_DUPLICATE

Type
craft\events\AuthorizationCheckEvent
Since
4.3.0

The event that is triggered when determining whether a user is authorized to duplicate an element.

To authorize the user, set craft\events\AuthorizationCheckEvent::$authorized to true.

php
use craft\events\AuthorizationCheckEvent;
use craft\services\Elements;
use yii\base\Event;

Event::on(
    Elements::class,
    Elements::EVENT_AUTHORIZE_DUPLICATE,
    function(AuthorizationCheckEvent $event) {
        $event->authorized = true;
    }
);

See also canDuplicate()


EVENT_AUTHORIZE_DUPLICATE_AS_DRAFT

Type
craft\events\AuthorizationCheckEvent
Since
5.0.0

The event that is triggered when determining whether a user is authorized to duplicate an element as an unpublished draft.

To authorize the user, set craft\events\AuthorizationCheckEvent::$authorized to true.

php
use craft\events\AuthorizationCheckEvent;
use craft\services\Elements;
use yii\base\Event;

Event::on(
    Elements::class,
    Elements::EVENT_AUTHORIZE_DUPLICATE,
    function(AuthorizationCheckEvent $event) {
        $event->authorized = true;
    }
);

See also canDuplicateAsDraft()


EVENT_AUTHORIZE_SAVE

Type
craft\events\AuthorizationCheckEvent
Since
4.3.0

The event that is triggered when determining whether a user is authorized to save an element in its current state.

To authorize the user, set craft\events\AuthorizationCheckEvent::$authorized to true.

php
use craft\events\AuthorizationCheckEvent;
use craft\services\Elements;
use yii\base\Event;

Event::on(
    Elements::class,
    Elements::EVENT_AUTHORIZE_SAVE,
    function(AuthorizationCheckEvent $event) {
        $event->authorized = true;
    }
);

See also canSave()


EVENT_AUTHORIZE_VIEW

Type
craft\events\AuthorizationCheckEvent
Since
4.3.0

The event that is triggered when determining whether a user is authorized to view an element’s edit page.

To authorize the user, set craft\events\AuthorizationCheckEvent::$authorized to true.

php
use craft\events\AuthorizationCheckEvent;
use craft\services\Elements;
use yii\base\Event;

Event::on(
    Elements::class,
    Elements::EVENT_AUTHORIZE_VIEW,
    function(AuthorizationCheckEvent $event) {
        $event->authorized = true;
    }
);

See also canView()


EVENT_BEFORE_BULK_OP

Type
craft\events\BulkOpEvent
Since
5.0.0

The event that is triggered before a bulk element operation has started.

Note that this won’t necessarily fire from the same request as EVENT_AFTER_BULK_OP.


EVENT_BEFORE_DELETE_ELEMENT

Type
craft\events\DeleteElementEvent

The event that is triggered before an element is deleted.


EVENT_BEFORE_DELETE_FOR_SITE

Type
craft\events\ElementEvent
Since
4.4.0

The event that is triggered before deleting an element for a single site.

See also:


EVENT_BEFORE_EAGER_LOAD_ELEMENTS

Type
craft\events\EagerLoadElementsEvent
Since
3.5.0

The event that is triggered before elements are eager-loaded.


EVENT_BEFORE_MERGE_CANONICAL_CHANGES

Type
craft\events\ElementEvent
Since
3.7.0

The event that is triggered before canonical element changes are merged into a derivative.


EVENT_BEFORE_PERFORM_ACTION

Type
craft\events\ElementActionEvent

The event that is triggered before an element action is performed.

You may set craft\events\CancelableEvent::$isValid to false to prevent the action from being performed.


EVENT_BEFORE_PROPAGATE_ELEMENT

Type
craft\events\MultiElementActionEvent

The event that is triggered before an element is propagated.


EVENT_BEFORE_PROPAGATE_ELEMENTS

Type
craft\events\ElementQueryEvent

The event that is triggered before propagating a batch of elements.


EVENT_BEFORE_RESAVE_ELEMENT

Type
craft\events\MultiElementActionEvent

The event that is triggered before an element is resaved.


EVENT_BEFORE_RESAVE_ELEMENTS

Type
craft\events\ElementQueryEvent

The event that is triggered before resaving a batch of elements.


EVENT_BEFORE_RESTORE_ELEMENT

Type
craft\events\ElementEvent
Since
3.1.0

The event that is triggered before an element is restored.


EVENT_BEFORE_SAVE_ELEMENT

Type
craft\events\ElementEvent

The event that is triggered before an element is saved.

If you want to ignore events for drafts or revisions, call craft\helpers\ElementHelper::isDraftOrRevision() from your event handler:

php
use craft\events\ElementEvent;
use craft\helpers\ElementHelper;
use craft\services\Elements;

Craft::$app->elements->on(Elements::EVENT_BEFORE_SAVE_ELEMENT, function(ElementEvent $e) {
    if (ElementHelper::isDraftOrRevision($e->element)) {
        return;
    }

    // ...
});

EVENT_BEFORE_UPDATE_SEARCH_INDEX

Type
craft\events\ElementEvent
Since
3.7.12

The event that is triggered before indexing an element’s search keywords, or queuing the element’s search keywords to be updated.

You may set craft\events\CancelableEvent::$isValid to false to prevent the search index from being updated.


EVENT_BEFORE_UPDATE_SLUG_AND_URI

Type
craft\events\ElementEvent

The event that is triggered before an element’s slug and URI are updated, usually following a Structure move.


EVENT_INVALIDATE_CACHES

Type
craft\events\InvalidateElementCachesEvent
Since
4.2.0

The event that is triggered when element caches are invalidated.


EVENT_REGISTER_ELEMENT_TYPES

Type
craft\events\RegisterComponentTypesEvent

The event that is triggered when registering element types.

Element types must implement craft\base\ElementInterface. craft\base\Element provides a base implementation.

See Element Types for documentation on creating element types.


Example

php
use craft\events\RegisterComponentTypesEvent;
use craft\services\Elements;
use yii\base\Event;

Event::on(Elements::class,
    Elements::EVENT_REGISTER_ELEMENT_TYPES,
    function(RegisterComponentTypesEvent $event) {
        $event->types[] = MyElementType::class;
    }
);

EVENT_SET_ELEMENT_URI

Type
craft\events\ElementEvent
Since
4.6.0

The event that is triggered when setting a unique URI on an element.

Event handlers must set $event->handled to true for their change to take effect.

See also setElementUri()