Craft 3 Class Reference

Appearance

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.
duplicatedElementIdsinteger[] – Stores a mapping of source element IDs to their duplicated element IDs.
duplicatedElementSourceIdsinteger[] – Stores a mapping of duplicated element IDs to their source element IDs.
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

duplicatedElementIds ​

Type
integer[]
Default value
[]

Stores a mapping of source element IDs to their duplicated element IDs.

View source

duplicatedElementSourceIds ​

Type
integer[]
Default value
[]
Since
3.4.0

Stores a mapping of duplicated element IDs to their source element IDs.

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.
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.
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.
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.
ensureBehaviors()Makes sure that the behaviors declared in behaviors() are attached to this component.
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.
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.
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.
saveElement()Handles all of the routine tasks that go along with saving elements.
setPlaceholderElement()Stores a placeholder element that element queries should use instead of populating a new element with a matching ID and site ID.
startCollectingCacheTags()Starts collecting element cache invalidation tags.
stopCollectingCacheTags()Stops collecting element cache invalidation tags, and returns a cache dependency object.
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.

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 (mixed) – The element action’s class name, or its config, with a type value and optionally a settings value

Returns ​

craft\base\ElementActionInterface – The element action

createEagerLoadingPlans() ​

Since
3.5.0

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

View source

Arguments ​

  • $with

Returns ​

craft\elements\db\EagerLoadPlan[]

createElement() ​

Creates an element with a given config.

View source

Arguments ​

  • $config (mixed) – The field’s class name, or its config, with a type value and optionally a settings value

Returns ​

craft\base\ElementInterface – 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 (mixed) – The element exporter’s class name, or its config, with a type value and optionally a settings value

Returns ​

craft\base\ElementExporterInterface – The element exporter

deleteElement() ​

Deletes an element.

View source

Arguments ​

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

Returns ​

boolean – Whether the element was deleted successfully

Throws ​

duplicateElement() ​

Duplicates an element.

View source

Arguments ​

Returns ​

craft\base\ElementInterface – The duplicated element

Throws ​

eagerLoadElements() ​

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

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\base\ElementInterface, 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\base\ElementInterface, 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.

getIsCollectingCacheTags() ​

Since
3.5.0

Returns whether we are currently collecting element cache invalidation tags.

See also:

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

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 ​

Returns ​

void

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 ​

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 ​

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)

Returns ​

boolean

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 ​

startCollectingCacheTags() ​

Since
3.5.0

Starts collecting element cache invalidation tags.

View source

stopCollectingCacheTags() ​

Since
3.5.0

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

View source

Returns ​

yii\caching\TagDependency

updateCanonicalElement() ​

Since
3.7.0

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

View source

Arguments ​

Returns ​

craft\base\ElementInterface – 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_DELETE_ELEMENT ​

Type
craft\events\ElementEvent

The event that is triggered after an element is deleted.

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

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

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

Type
craft\events\DeleteElementEvent

The event that is triggered before an element is deleted.

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

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

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_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;
    }
);