NestedElementQueryTrait

Type

Trait

Namespace

craft\elements\db

Implemented by

craft\elements\db\AddressQuery, craft\elements\db\EntryQuery

Since

5.5.0

Trait NestedElementQueryTrait

View source

Public Properties

Property	Description
allowOwnerDrafts	boolean, null – Whether the owner elements can be drafts.
allowOwnerRevisions	boolean, null – Whether the owner elements can be revisions.
fieldId	mixed – The field ID(s) that the resulting {elements} must belong to.
ownerId	mixed – The owner element ID(s) that the resulting {elements} must belong to.
primaryOwnerId	mixed – The primary owner element ID(s) that the resulting {elements} must belong to.

allowOwnerDrafts

Type

boolean, null

Default value

null

Since

5.0.0

Whether the owner elements can be drafts.

View source

allowOwnerRevisions

Type

boolean, null

Default value

null

Since

5.0.0

Whether the owner elements can be revisions.

View source

fieldId

Type

mixed

Default value

null

Since

5.0.0

The field ID(s) that the resulting {elements} must belong to.

View source

ownerId

Type

mixed

Default value

null

Since

5.0.0

The owner element ID(s) that the resulting {elements} must belong to.

View source

primaryOwnerId

Type

mixed

Default value

null

Since

5.0.0

The primary owner element ID(s) that the resulting {elements} must belong to.

View source

Public Methods

Method	Description
__set()	Sets the value of a component property.
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.
createElement()	Converts a found row into an element instance.
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.
owner()	Sets the ownerId() and \craft\elements\db\siteId() parameters based on a given element.
ownerId()	Narrows the query results based on the owner element of the {elements}, per the owners’ IDs.
primaryOwner()	Sets the primaryOwnerId() and \craft\elements\db\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.

__set()

Sets the value of a component property.

This method will check in the following order and act accordingly:

• a property defined by a setter: set the property value
• an event in the format of "on xyz": attach the handler to the event "xyz"
• a behavior in the format of "as xyz": attach the behavior named as "xyz"
• a property of a behavior: set the behavior property value

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing $component->property = $value;.

View source

Arguments

• $name (string) – The property name or the event name
• $value (mixed) – The property value

Throws

• yii\base\UnknownPropertyException
  if the property is not defined
• yii\base\InvalidCallException
  if the property is read-only.

allowOwnerDrafts()

Since

5.0.0

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.

View source

Arguments

• $value (boolean, null) – The property value

Returns

static – Self reference

allowOwnerRevisions()

Since

5.0.0

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.

View source

Arguments

• $value (boolean, null) – The property value

Returns

static – Self reference

createElement()

Since

3.6.0

Converts a found row into an element instance.

View source

Arguments

• $row (array)

Returns

craft\base\ElementInterface

field()

Since

5.0.0

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.

View source

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()

Since

5.0.0

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.

View source

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()

Since

5.0.0

Sets the ownerId() and \craft\elements\db\siteId() parameters based on a given element.

View source

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()

Since

5.0.0

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.

View source

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()

Since

5.0.0

Sets the primaryOwnerId() and \craft\elements\db\siteId() parameters based on a given element.

View source

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()

Since

5.0.0

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.

View source

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();

Protected Methods

Method	Description
cacheTags()	Returns any cache invalidation tags that caches involving this element query should use as dependencies.

cacheTags()

Since

3.5.0

Returns any cache invalidation tags that caches involving this element query should use as dependencies.

Use the most specific tag(s) possible, to reduce the likelihood of pointless cache clearing.

When elements are created/updated/deleted, their craft\base\ElementInterface::getCacheTags() method will be called, and any caches that have those tags listed as dependencies will be invalidated.

View source

Returns

string[]