NestedElementQueryInterface
- Type
- Interface
- Namespace
- craft\elements\db
- Extends
- craft\elements\db\ElementQueryInterface
- Implemented by
- craft\elements\db\AddressQuery, craft\elements\db\EntryQuery
- Since
- 5.4.9
NestedElementQueryInterface defines the common interface to be implemented by element query classes which can query for nested elements.
An implementation of this interface is provided by craft\elements\db\NestedElementQueryTrait.
Public Methods
| Method | Description |
|---|---|
| addOrderBy() | Adds additional ORDER BY columns to the query. |
| afterPopulate() | Performs any post-population processing on elements. |
| all() | Executes the query and returns all results as an array. |
| allowOwnerDrafts() | Narrows the query results based on whether the {elements}’ owners are drafts. |
| allowOwnerRevisions() | Narrows the query results based on whether the {elements}’ owners are revisions. |
| ancestorDist() | Narrows the query results to only {elements} that are up to a certain distance away from the {element} specified by ancestorOf(). |
| ancestorOf() | Narrows the query results to only {elements} that are ancestors of another {element} in its structure. |
| andFilterWhere() | Adds an additional WHERE condition to the existing one ignoring empty parameters. |
| andNotRelatedTo() | Narrows the query results to only {elements} that are not related to certain other elements. |
| andRelatedTo() | Narrows the query results to only {elements} that are related to certain other elements. |
| andWhere() | Adds an additional WHERE condition to the existing one. |
| andWith() | Causes the query to return matching {elements} eager-loaded with related elements, in addition to the elements that were already specified by with(). |
| archived() | Sets the $archived property. |
| asArray() | Causes the query to return matching {elements} as arrays of data, rather than [[{element-class}]] objects. |
| collect() | Executes the query and returns all results as a collection. |
| count() | Returns the number of records. |
| createElement() | Converts a found row into an element instance. |
| dateCreated() | Narrows the query results based on the {elements}’ creation dates. |
| dateUpdated() | Narrows the query results based on the {elements}’ last-updated dates. |
| descendantDist() | Narrows the query results to only {elements} that are up to a certain distance away from the {element} specified by descendantOf(). |
| descendantOf() | Narrows the query results to only {elements} that are descendants of another {element} in its structure. |
| draftCreator() | Narrows the query results to only drafts created by a given user. |
| draftId() | Narrows the query results based on the {elements}’ draft’s ID (from the drafts table). |
| draftOf() | Narrows the query results to only drafts of a given {element}. |
| drafts() | Narrows the query results to only drafts {elements}. |
| eagerly() | Causes the query to be used to eager-load results for the query’s source element and any other elements in its collection. |
| emulateExecution() | Sets whether to emulate query execution, preventing any interaction with data storage. |
| exists() | Returns a value indicating whether the query result contains any row of data. |
| extraFields() | Returns the list of additional fields that can be returned by toArray() in addition to those listed in fields(). |
| field() | Narrows the query results based on the field the {elements} are contained by. |
| fieldId() | Narrows the query results based on the field the {elements} are contained by, per the fields’ IDs. |
| fields() | Returns the list of fields that should be returned by default by toArray() when no specific fields are specified. |
| filterWhere() | Sets the WHERE part of the query ignoring empty parameters. |
| fixedOrder() | Causes the query results to be returned in the order specified by id(). |
| hasDescendants() | Narrows the query results based on whether the {elements} have any descendants in their structure. |
| id() | Narrows the query results based on the {elements}’ IDs. |
| ids() | Executes the query and returns the IDs of the resulting elements. |
| ignorePlaceholders() | Causes the query to return matching {elements} as they are stored in the database, ignoring matching placeholder elements that were set by craft\services\Elements::setPlaceholderElement(). |
| inBulkOp() | Narrows the query results to only {elements} that were involved in a bulk element operation. |
| inReverse() | Causes the query results to be returned in reverse order. |
| indexBy() | Sets the indexBy() property. |
| language() | Determines which site(s) the {elements} should be queried in, based on their language. |
| leaves() | Narrows the query results based on whether the {elements} are “leaves” ({elements} with no descendants). |
| level() | Narrows the query results based on the {elements}’ level within the structure. |
| limit() | Sets the LIMIT part of the query. |
| nextSiblingOf() | Narrows the query results to only the {element} that comes immediately after another {element} in its structure. |
| notRelatedTo() | Narrows the query results to only {elements} that are not related to certain other elements. |
| nth() | Executes the query and returns a single row of result at a given offset. |
| offset() | Sets the OFFSET part of the query. |
| one() | Executes the query and returns a single row of result. |
| orFilterWhere() | Adds an additional WHERE condition to the existing one ignoring empty parameters. |
| orWhere() | Adds an additional WHERE condition to the existing one. |
| orderBy() | Sets the ORDER BY part of the query. |
| owner() | Sets the ownerId() and siteId() parameters based on a given element. |
| ownerId() | Narrows the query results based on the owner element of the {elements}, per the owners’ IDs. |
| positionedAfter() | Narrows the query results to only {elements} that are positioned after another {element} in its structure. |
| positionedBefore() | Narrows the query results to only {elements} that are positioned before another {element} in its structure. |
| preferSites() | If unique() is set, this determines which site should be selected when querying multi-site elements. |
| prepForEagerLoading() | Prepares the query for lazy eager loading. |
| prevSiblingOf() | Narrows the query results to only the {element} that comes immediately before another {element} in its structure. |
| primaryOwner() | Sets the primaryOwnerId() and siteId() parameters based on a given element. |
| primaryOwnerId() | Narrows the query results based on the primary owner element of the {elements}, per the owners’ IDs. |
| provisionalDrafts() | Narrows the query results to only provisional drafts. |
| ref() | Narrows the query results based on a reference string. |
| relatedTo() | Narrows the query results to only {elements} that are related to certain other elements. |
| revisionCreator() | Narrows the query results to only revisions created by a given user. |
| revisionId() | Narrows the query results based on the {elements}’ revision’s ID (from the revisions table). |
| revisionOf() | Narrows the query results to only revisions of a given {element}. |
| revisions() | Narrows the query results to only revision {elements}. |
| savedDraftsOnly() | Narrows the query results to only unpublished drafts which have been saved after initial creation. |
| search() | Narrows the query results to only {elements} that match a search query. |
| siblingOf() | Narrows the query results to only {elements} that are siblings of another {element} in its structure. |
| site() | Determines which site(s) the {elements} should be queried in. |
| siteId() | Determines which site(s) the {elements} should be queried in, per the site’s ID. |
| siteSettingsId() | Narrows the query results based on the {elements}’ IDs in the elements_sites table. |
| slug() | Narrows the query results based on the {elements}’ slugs. |
| status() | Narrows the query results based on the {elements}’ statuses. |
| structureId() | Determines which structure data should be joined into the query. |
| title() | Narrows the query results based on the {elements}’ titles. |
| toArray() | Converts the object into an array. |
| trashed() | Narrows the query results to only {elements} that have been soft-deleted. |
| uid() | Narrows the query results based on the {elements}’ UIDs. |
| unique() | Determines whether only elements with unique IDs should be returned by the query. |
| uri() | Narrows the query results based on the {elements}’ URIs. |
| wasCountEagerLoaded() | Returns whether the query result count was already eager loaded by the query's source element. |
| wasEagerLoaded() | Returns whether the query results were already eager loaded by the query's source element. |
| where() | Sets the WHERE part of the query. |
| with() | Causes the query to return matching {elements} eager-loaded with related elements. |
| withCustomFields() | Sets whether custom fields should be factored into the query. |
| withStructure() | Explicitly determines whether the query should join in the structure data. |
allowOwnerDrafts()
Narrows the query results based on whether the {elements}’ owners are drafts.
Possible values include:
| Value | Fetches {elements}… |
|---|---|
true | which can belong to a draft. |
false | which cannot belong to a draft. |
Arguments
Returns
static – Self reference
allowOwnerRevisions()
Narrows the query results based on whether the {elements}’ owners are revisions.
Possible values include:
| Value | Fetches {elements}… |
|---|---|
true | which can belong to a revision. |
false | which cannot belong to a revision. |
Arguments
Returns
static – Self reference
field()
Narrows the query results based on the field the {elements} are contained by.
Possible values include:
| Value | Fetches {elements}… |
|---|---|
'foo' | in a field with a handle of foo. |
['foo', 'bar'] | in a field with a handle of foo or bar. |
a \craft\elements\db\craft\fields\Matrix object | in a field represented by the object. |
Arguments
$value(mixed) – The property value
Returns
static – Self reference
Example
twig
{# Fetch {elements} in the Foo field #}
{% set {elements-var} = {twig-method}
.field('foo')
.all() %}php
// Fetch {elements} in the Foo field
${elements-var} = {php-method}
->field('foo')
->all();fieldId()
Narrows the query results based on the field the {elements} are contained by, per the fields’ IDs.
Possible values include:
| Value | Fetches {elements}… |
|---|---|
1 | in a field with an ID of 1. |
'not 1' | not in a field with an ID of 1. |
[1, 2] | in a field with an ID of 1 or 2. |
['not', 1, 2] | not in a field with an ID of 1 or 2. |
Arguments
$value(mixed) – The property value
Returns
static – Self reference
Example
twig
{# Fetch {elements} in the field with an ID of 1 #}
{% set {elements-var} = {twig-method}
.fieldId(1)
.all() %}php
// Fetch {elements} in the field with an ID of 1
${elements-var} = {php-method}
->fieldId(1)
->all();owner()
Sets the ownerId() and siteId() parameters based on a given element.
Arguments
$owner(craft\base\ElementInterface) – The owner element
Returns
static – Self reference
Example
twig
{# Fetch {elements} created for this entry #}
{% set {elements-var} = {twig-method}
.owner(myEntry)
.all() %}php
// Fetch {elements} created for this entry
${elements-var} = {php-method}
->owner($myEntry)
->all();ownerId()
Narrows the query results based on the owner element of the {elements}, per the owners’ IDs.
Possible values include:
| Value | Fetches {elements}… |
|---|---|
1 | created for an element with an ID of 1. |
[1, 2] | created for an element with an ID of 1 or 2. |
Arguments
$value(mixed) – The property value
Returns
static – Self reference
Example
twig
{# Fetch {elements} created for an element with an ID of 1 #}
{% set {elements-var} = {twig-method}
.ownerId(1)
.all() %}php
// Fetch {elements} created for an element with an ID of 1
${elements-var} = {php-method}
->ownerId(1)
->all();primaryOwner()
Sets the primaryOwnerId() and siteId() parameters based on a given element.
Arguments
$primaryOwner(craft\base\ElementInterface) – The primary owner element
Returns
static – Self reference
Example
twig
{# Fetch {elements} created for this entry #}
{% set {elements-var} = {twig-method}
.primaryOwner(myEntry)
.all() %}php
// Fetch {elements} created for this entry
${elements-var} = {php-method}
->primaryOwner($myEntry)
->all();primaryOwnerId()
Narrows the query results based on the primary owner element of the {elements}, per the owners’ IDs.
Possible values include:
| Value | Fetches {elements}… |
|---|---|
1 | created for an element with an ID of 1. |
[1, 2] | created for an element with an ID of 1 or 2. |
Arguments
$value(mixed) – The property value
Returns
static – Self reference
Example
twig
{# Fetch {elements} created for an element with an ID of 1 #}
{% set {elements-var} = {twig-method}
.primaryOwnerId(1)
.all() %}php
// Fetch {elements} created for an element with an ID of 1
${elements-var} = {php-method}
->primaryOwnerId(1)
->all();