Craft 2 Class Reference

Class ElementsService

Package
craft.app.services
Namespace
Craft
Inheritance
class ElementsService » BaseApplicationComponent » \CApplicationComponent » \CComponent
Implements
\IApplicationComponent
Since
1.0
Source Code
craft/app/services/ElementsService.php

ElementsService provides APIs for managing elements.

An instance of ElementsService is globally accessible in Craft via craft()->elements.

Public Properties
Property Type Description Defined By
allActions IElementAction[] Returns all installed element actions. ElementsService
allElementTypes IElementType[] Returns all installed element types. ElementsService
behaviors array the behaviors that should be attached to this component. \CApplicationComponent
isInitialized bool Checks if this application component has been initialized. \CApplicationComponent
totalElements int Returns the total number of elements that match a given criteria. ElementsService
Public Methods
Method Description Defined By
__call() Calls the named method which is not a class method. \CComponent
__get() Returns a property value, an event handler list or a behavior based on its name. \CComponent
__isset() Checks if a property value is null. \CComponent
__set() Sets value of a component property. \CComponent
__unset() Sets a component property to be null. \CComponent
asa() Returns the named behavior object. \CComponent
attachBehavior() Attaches a behavior to this component. \CComponent
attachBehaviors() Attaches a list of behaviors to the component. \CComponent
attachEventHandler() Attaches an event handler to an event. \CComponent
buildElementsQuery() Preps a DbCommand object for querying for elements, based on a given element criteria. ElementsService
canGetProperty() Determines whether a property can be read. \CComponent
canSetProperty() Determines whether a property can be set. \CComponent
deleteElementById() Deletes an element(s) by its ID(s). ElementsService
deleteElementsByType() Deletes elements by a given type. ElementsService
detachBehavior() Detaches a behavior from the component. \CComponent
detachBehaviors() Detaches all behaviors from the component. \CComponent
detachEventHandler() Detaches an existing event handler. \CComponent
disableBehavior() Disables an attached behavior. \CComponent
disableBehaviors() Disables all behaviors attached to this component. \CComponent
eagerLoadElements() Eager-loads additional elements onto a given set of elements. ElementsService
enableBehavior() Enables an attached behavior. \CComponent
enableBehaviors() Enables all behaviors attached to this component. \CComponent
evaluateExpression() Evaluates a PHP expression or callback under the context of this component. \CComponent
findElements() Finds elements. ElementsService
getAction() Returns an element action by its class handle. ElementsService
getAllActions() Returns all installed element actions. ElementsService
getAllElementTypes() Returns all installed element types. ElementsService
getCriteria() Returns an element criteria model for a given element type. ElementsService
getElementById() Returns an element by its ID. ElementsService
getElementByUri() Returns an element by its URI. ElementsService
getElementType() Returns an element type by its class handle. ElementsService
getElementTypeById() Returns the element type(s) used by the element of a given ID(s). ElementsService
getElementUriForLocale() Returns an element’s URI for a given locale. ElementsService
getEnabledLocalesForElement() Returns the locales that a given element is enabled in. ElementsService
getEventHandlers() Returns the list of attached event handlers for an event. \CComponent
getIsInitialized() Checks if this application component has been initialized. \CApplicationComponent
getTotalElements() Returns the total number of elements that match a given criteria. ElementsService
handleRequestEnd() Perform element clean-up work. ElementsService
hasEvent() Determines whether an event is defined. \CComponent
hasEventHandler() Checks whether the named event has attached handlers. \CComponent
hasProperty() Determines whether a property is defined. \CComponent
init() Initializes the application component. \CApplicationComponent
isInitialized() Checks if this application component has been initialized yet, or not. BaseApplicationComponent
mergeElementsByIds() Merges two elements together. ElementsService
onBeforeBuildElementsQuery() Fires an 'onBeforeBuildElementsQuery' event. ElementsService
onBeforeDeleteElements() Fires an 'onBeforeDeleteElements' event. ElementsService
onBeforePerformAction() Fires an 'onBeforePerformAction' event. ElementsService
onBeforeSaveElement() Fires an 'onBeforeSaveElement' event. ElementsService
onBuildElementsQuery() Fires an 'onBuildElementsQuery' event. ElementsService
onMergeElements() Fires an 'onMergeElements' event. ElementsService
onPerformAction() Fires an 'onPerformAction' event. ElementsService
onPopulateElement() Fires an 'onPopulateElement' event. ElementsService
onPopulateElements() Fires an 'onPopulateElements' event. ElementsService
onSaveElement() Fires an 'onSaveElement' event. ElementsService
parseRefs() Parses a string for element reference tags. ElementsService
populateElements() Populates element models from a given element query's result set. ElementsService
raiseEvent() Raises an event. \CComponent
saveElement() Handles all of the routine tasks that go along with saving elements. ElementsService
setPlaceholderElement() Stores a placeholder element that findElements() should use instead of populating a new element with a matching ID and locale. ElementsService
updateDescendantSlugsAndUris() Updates an element’s descendants’ slugs and URIs. ElementsService
updateElementSlugAndUri() Updates an element’s slug and URI, along with any descendants. ElementsService
updateElementSlugAndUriInOtherLocales() Updates an element’s slug and URI, for any locales besides the given one. ElementsService
Events
Event Description Defined By
onBeforeBuildElementsQuery Fires an 'onBeforeBuildElementsQuery' event. ElementsService
onBuildElementsQuery Fires an 'onBuildElementsQuery' event. ElementsService
onPopulateElement Fires an 'onPopulateElement' event. ElementsService
onPopulateElements Fires an 'onPopulateElements' event. ElementsService
onMergeElements Fires an 'onMergeElements' event. ElementsService
onBeforeDeleteElements Fires an 'onBeforeDeleteElements' event. ElementsService
onBeforeSaveElement Fires an 'onBeforeSaveElement' event. ElementsService
onSaveElement Fires an 'onSaveElement' event. ElementsService
onBeforePerformAction Fires an 'onBeforePerformAction' event. ElementsService
onPerformAction Fires an 'onPerformAction' event. ElementsService

Property Details

allActions public property #

Returns all installed element actions.

public IElementAction[] getAllActions()

allElementTypes public property #

Returns all installed element types.

public IElementType[] getAllElementTypes()

totalElements public property #

Returns the total number of elements that match a given criteria.

public int getTotalElements(ElementCriteriaModel $criteria = null)

Method Details

buildElementsQuery() public method #

Preps a DbCommand object for querying for elements, based on a given element criteria.

public DbCommand|false buildElementsQuery(ElementCriteriaModel &$criteria = null, string &$contentTable = null, array &$fieldColumns = null, bool $justIds = false)
&$criteria ElementCriteriaModel The element criteria model
&$contentTable string The content table that should be joined in. (This variable will actually get defined by buildElementsQuery(), and is passed by reference so whatever’s calling the method will have access to its value.)
&$fieldColumns array Info about the content field columns being selected. (This variable will actually get defined by buildElementsQuery(), and is passed by reference so whatever’s calling the method will have access to its value.)
$justIds bool Whether the method should only return an array of the IDs of the matched elements. Defaults to false.
Returns DbCommand / false The DbCommand object, or false if the method was able to determine ahead of time that there’s no chance any elements are going to be found with the given parameters.

deleteElementById() public method #

Deletes an element(s) by its ID(s).

public bool deleteElementById(int|array $elementIds)
$elementIds int / array The element’s ID, or an array of elements’ IDs.
Returns bool Whether the element(s) were deleted successfully.

deleteElementsByType() public method #

Deletes elements by a given type.

public bool deleteElementsByType(string $type)
$type string The element type class handle.
Returns bool Whether the elements were deleted successfully.

eagerLoadElements() public method #

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

public void eagerLoadElements(BaseElementType $elementType, array $elements, string|array $with)
$elementType BaseElementType The root element type
$elements array The root element models that should be updated with the eager-loaded elements
$with string / array Dot-delimited paths of the elements that should be eager-loaded into the root elements
Returns void

findElements() public method #

Finds elements.

public array findElements(ElementCriteriaModel $criteria = null, bool $justIds = false)
$criteria ElementCriteriaModel An element criteria model that defines the parameters for the elements we should be looking for.
$justIds bool Whether the method should only return an array of the IDs of the matched elements. Defaults to false.
Returns array The matched elements, or their IDs, depending on $justIds.

getAction() public method #

Returns an element action by its class handle.

public IElementAction|null getAction(string $class)
$class string The element action class handle.
Returns IElementAction / null The element action, or null.

getAllActions() public method #

Returns all installed element actions.

public IElementAction[] getAllActions()
Returns IElementAction[] The installed element actions.

getAllElementTypes() public method #

Returns all installed element types.

public IElementType[] getAllElementTypes()
Returns IElementType[] The installed element types.

getCriteria() public method #

Returns an element criteria model for a given element type.

This should be the starting point any time you want to fetch elements in Craft.

$criteria = craft()->elements->getCriteria(ElementType::Entry);
$criteria->section = 'news';
$entries = $criteria->find();
public ElementCriteriaModel getCriteria(string $type, mixed $attributes = null)
$type string The element type class handle (e.g. one of the values in the ElementType enum).
$attributes mixed Any criteria attribute values that should be pre-populated on the criteria model.
Returns ElementCriteriaModel An element criteria model, wired to fetch elements of the given $type.

getElementById() public method #

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 $elementId is, so you should definitely pass it if it’s known.

The element’s status will not be a factor when using this method.

public BaseElementModel|null getElementById(int $elementId, null $elementType = null, string $localeId = null)
$elementId int The element’s ID.
$elementType null The element type’s class handle.
$localeId string The locale to fetch the element in. Defaults to craft()->language.
Returns BaseElementModel / null The matching element, or null.

getElementByUri() public method #

Returns an element by its URI.

public BaseElementModel|null getElementByUri(string $uri, string|null $localeId = null, bool $enabledOnly = false)
$uri string The element’s URI.
$localeId string / null The locale to look for the URI in, and to return the element in. Defaults to craft()->language.
$enabledOnly bool Whether to only look for an enabled element. Defaults to false.
Returns BaseElementModel / null The matching element, or null.

getElementType() public method #

Returns an element type by its class handle.

public IElementType|null getElementType(string $class)
$class string The element type class handle.
Returns IElementType / null The element type, or null.

getElementTypeById() public method #

Returns the element type(s) used by the element of a given ID(s).

If a single ID is passed in (an int), then a single element type will be returned (a string), or null if no element exists by that ID.

If an array is passed in, then an array will be returned.

public string|array|null getElementTypeById(int|array $elementId)
$elementId int / array An element’s ID, or an array of elements’ IDs.
Returns string / array / null The element type(s).

getElementUriForLocale() public method #

Returns an element’s URI for a given locale.

public string|null getElementUriForLocale(int $elementId, string $localeId)
$elementId int The element’s ID.
$localeId string The locale to search for the element’s URI in.
Returns string / null The element’s URI, or null.

getEnabledLocalesForElement() public method #

Returns the locales that a given element is enabled in.

public array getEnabledLocalesForElement(int $elementId)
$elementId int The element’s ID.
Returns array The locales that the element is enabled in. If the element could not be found, an empty array will be returned.

getTotalElements() public method #

Returns the total number of elements that match a given criteria.

public int getTotalElements(ElementCriteriaModel $criteria = null)
$criteria ElementCriteriaModel An element criteria model that defines the parameters for the elements we should be counting.
Returns int The total number of elements that match the criteria.

handleRequestEnd() public method #

Perform element clean-up work.

public void handleRequestEnd()

mergeElementsByIds() public method #

Merges two elements together.

This method will update the following:

public bool mergeElementsByIds(int $mergedElementId, int $prevailingElementId)
$mergedElementId int The ID of the element that is going away.
$prevailingElementId int The ID of the element that is sticking around.
Returns bool Whether the elements were merged successfully.

onBeforeBuildElementsQuery() public method #

Fires an 'onBeforeBuildElementsQuery' event.

public null onBeforeBuildElementsQuery(Event $event)
$event Event

onBeforeDeleteElements() public method #

Fires an 'onBeforeDeleteElements' event.

public null onBeforeDeleteElements(Event $event)
$event Event

onBeforePerformAction() public method #

Fires an 'onBeforePerformAction' event.

public null onBeforePerformAction(Event $event)
$event Event

onBeforeSaveElement() public method #

Fires an 'onBeforeSaveElement' event.

public null onBeforeSaveElement(Event $event)
$event Event

onBuildElementsQuery() public method #

Fires an 'onBuildElementsQuery' event.

public null onBuildElementsQuery(Event $event)
$event Event

onMergeElements() public method #

Fires an 'onMergeElements' event.

public null onMergeElements(Event $event)
$event Event

onPerformAction() public method #

Fires an 'onPerformAction' event.

public null onPerformAction(Event $event)
$event Event

onPopulateElement() public method #

Fires an 'onPopulateElement' event.

public null onPopulateElement(Event $event)
$event Event

onPopulateElements() public method #

Fires an 'onPopulateElements' event.

public null onPopulateElements(Event $event)
$event Event

onSaveElement() public method #

Fires an 'onSaveElement' event.

public null onSaveElement(Event $event)
$event Event

parseRefs() public method #

Parses a string for element reference tags.

public string parseRefs(string $str)
$str string The string to parse.
Returns string The parsed string.

populateElements() public method #

Populates element models from a given element query's result set.

public BaseElementModel[] populateElements(array $results, ElementCriteriaModel $criteria, string $contentTable, array $fieldColumns)
$results array The result set of an element query
$criteria ElementCriteriaModel The element criteria model
$contentTable string The content table that was joined in by buildElementsQuery()
$fieldColumns array Info about the content field columns being selected
Returns BaseElementModel[] The populated element models.

saveElement() public method #

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

Those tasks include:

This method should be called by a service’s “saveX()” method, after it is done validating any attributes on the element that are of particular concern to its element type. For example, if the element were an entry, saveElement() should be called only after the entry’s sectionId and typeId attributes had been validated to ensure that they point to valid section and entry type IDs.

public bool saveElement(BaseElementModel $element, bool|null $validateContent = null)
$element BaseElementModel The element that is being saved
$validateContent bool / null Whether the element's content should be validated. If left 'null', it will depend on whether the element is enabled or not.
Returns bool

setPlaceholderElement() public method #

Stores a placeholder element that findElements() should use instead of populating a new element with a matching ID and locale.

This is used by Live Preview and Sharing features.

public null setPlaceholderElement(BaseElementModel $element)
$element BaseElementModel The element currently being edited by Live Preview.

updateDescendantSlugsAndUris() public method #

Updates an element’s descendants’ slugs and URIs.

public null updateDescendantSlugsAndUris(BaseElementModel $element, bool $updateOtherLocales = true, bool $asTask = false)
$element BaseElementModel The element whose descendants should be updated.
$updateOtherLocales bool Whether the element’s other locales should also be updated.
$asTask bool Whether the descendants’ slugs and URIs should be updated via a background task.

updateElementSlugAndUri() public method #

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

public null updateElementSlugAndUri(BaseElementModel $element, bool $updateOtherLocales = true, bool $updateDescendants = true, bool $asTask = false)
$element BaseElementModel The element to update.
$updateOtherLocales bool Whether the element’s other locales should also be updated.
$updateDescendants bool Whether the element’s descendants should also be updated.
$asTask bool Whether the element’s slug and URI should be updated via a background task.

updateElementSlugAndUriInOtherLocales() public method #

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

public null updateElementSlugAndUriInOtherLocales(BaseElementModel $element)
$element BaseElementModel The element to update.