Property Details

$ancestorDist public property #

The maximum number of levels that results may be separated from ancestorOf().

public integer, null $ancestorDist = null

$ancestorOf public property #

The element (or its ID) that results must be an ancestor of.

public integer, craft\base\ElementInterface, null $ancestorOf = null

$archived public property #

Whether to return only archived elements.

public boolean $archived = false

$asArray public property #

Whether to return each element as an array. If false (default), an object of $elementType will be created to represent each element.

public boolean $asArray = false

$contentTable public property #

The content table that will be joined by this query.

public string, null $contentTable = '{{%content}}'

$customFields public property #

The fields that may be involved in this query.

public craft\base\FieldInterface[], null $customFields = null

$dateCreated public property #

When the resulting elements must have been created.

public mixed $dateCreated = null

$dateUpdated public property #

When the resulting elements must have been last updated.

public mixed $dateUpdated = null

$defaultOrderBy protected property #

The default orderBy() value to use if orderBy() is empty but not null.

protected array $defaultOrderBy = ['elements.dateCreated' => SORT_DESC]

$descendantDist public property #

The maximum number of levels that results may be separated from descendantOf().

public integer, null $descendantDist = null

$descendantOf public property #

The element (or its ID) that results must be a descendant of.

public integer, craft\base\ElementInterface, null $descendantOf = null

$elementType public property #

The name of the craft\base\ElementInterface class.

public string, null $elementType = null

$enabledForSite public property #

Whether the elements must be enabled for the chosen site.

public boolean $enabledForSite = true

$fixedOrder public property #

Whether results should be returned in the order specified by id().

public boolean $fixedOrder = false

$id public property #

The element ID(s). Prefix IDs with "not " to exclude them.

public integer, integer[], false, null $id = null

$inReverse public property #

Whether the results should be queried in reverse.

public boolean $inReverse = false

$level public property #

The element’s level within the structure

public mixed $level = null

$nextSiblingOf public property #

The element (or its ID) that the result must be the next sibling of.

public integer, craft\base\ElementInterface, null $nextSiblingOf = null

$orderBy public property #

How to sort the query results. This is used to construct the ORDER BY clause in a SQL statement. The array keys are the columns to be sorted by, and the array values are the corresponding sort directions which can be either SORT_ASC or SORT_DESC. The array may also contain yii\db\ExpressionInterface objects. If that is the case, the expressions will be converted into strings without any change.

public array $orderBy = ''

$positionedAfter public property #

The element (or its ID) that the results must be positioned after.

public integer, craft\base\ElementInterface, null $positionedAfter = null

$positionedBefore public property #

The element (or its ID) that the results must be positioned before.

public integer, craft\base\ElementInterface, null $positionedBefore = null

$prevSiblingOf public property #

The element (or its ID) that the result must be the previous sibling of.

public integer, craft\base\ElementInterface, null $prevSiblingOf = null

$query public property #

The query object created by prepare()

See also prepare().

public craft\db\Query, null $query = null

$ref public property #

The reference code(s) used to identify the element(s). This property is set when accessing elements via their reference tags, e.g. {entry:section/slug}.

public string, string[], null $ref = null

$relatedTo public property #

The element relation criteria.

public integer, array, craft\base\ElementInterface, null $relatedTo = null

$search public property #

The search term to filter the resulting elements by.

public string, array, craft\search\SearchQuery, null $search = null

$siblingOf public property #

The element (or its ID) that the results must be a sibling of.

public integer, craft\base\ElementInterface, null $siblingOf = null

$siteId public property #

The site ID that the elements should be returned in.

public integer, null $siteId = null

$slug public property #

The slug that resulting elements must have.

public string, string[], null $slug = null

$status public property #

The status(es) that the resulting elements must have.

public string, string[], null $status = ['enabled']

$structureId public property #

The structure ID that should be used to join in the structureelements table.

public integer, false, null $structureId = null

$subQuery public property #

The subselect’s query object created by prepare()

See also prepare().

public craft\db\Query, null $subQuery = null

$title public property #

The title that resulting elements must have.

public string, string[], null $title = null

$uid public property #

The element UID(s). Prefix UIDs with "not " to exclude them.

public string, string[], null $uid = null

$uri public property #

The URI that the resulting element must have.

public string, string[], null $uri = null

$with public property #

The eager-loading declaration

public string, array, null $with = null

$withStructure public property #

Whether element structure data should automatically be left-joined into the query.

public boolean, null $withStructure = null

Method Details

__call() public method #

Calls the named method which is not a class method.

This method will check if any attached behavior has the named method and will execute it if available.

Do not call this method directly as it is a PHP magic method that will be implicitly called when an unknown method is being invoked.

public mixed __call ( $name, $params )

__construct() public method #

Constructor

public void __construct ( \craft\elements\db\string $elementType, array $config = [] )

__get() public method #

Returns the value of a component property.

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

• a property defined by a getter: return the getter result
• a property of a behavior: return the behavior property value

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

public mixed __get ( $name )

__isset() public method #

Checks if a property is set, i.e. defined and not null.

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

• a property defined by a setter: return whether the property is set
• a property of a behavior: return whether the property is set
• return false for non existing properties

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

public boolean __isset ( $name )

__set() public method #

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;.

public void __set ( $name, $value )

addOrderBy() public method #

Adds additional ORDER BY columns to the query.

public $this addOrderBy ( $columns )

afterPrepare() protected method #

This method is called at the end of preparing an element query for the query builder.

It is called at the beginning of prepare(), right after $query and $subQuery have been created.

See also:

• prepare()
• beforePrepare()

protected boolean afterPrepare ( )

all() public method #

Executes the query and returns all results as an array.

public array all ( $db = null )

ancestorDist() public method #

Sets the ancestorDist() property.

public static ancestorDist ( \craft\elements\db\int $value = null )

ancestorOf() public method #

Sets the ancestorOf() property.

public static ancestorOf ( $value )

archived() public method #

Sets the archived() property.

public static archived ( \craft\elements\db\bool $value = true )

asArray() public method #

Sets the asArray() property.

public static asArray ( \craft\elements\db\bool $value = true )

beforePrepare() protected method #

This method is called at the beginning of preparing an element query for the query builder.

The main Query object being prepared for the query builder is available via $query. The subselect’s Query object being prepared is available via $subQuery. The role of the subselect query is to apply conditions to the query and narrow the result set down to just the elements that should actually be returned. The role of the main query is to join in any tables that should be included in the results, and select all of the columns that should be included in the results.

See also:

• prepare()
• afterPrepare()

protected boolean beforePrepare ( )

behaviors() public method #

Returns a list of behaviors that this component should behave as.

Child classes may override this method to specify the behaviors they want to behave as.

The return value of this method should be an array of behavior objects or configurations indexed by behavior names. A behavior configuration can be either a string specifying the behavior class or an array of the following structure:

'behaviorName' => [
    'class' => 'BehaviorClass',
    'property1' => 'value1',
    'property2' => 'value2',
]

Note that a behavior class must extend from \craft\elements\db\Behavior. Behaviors can be attached using a name or anonymously. When a name is used as the array key, using this name, the behavior can later be retrieved using getBehavior() or be detached using detachBehavior(). Anonymous behaviors can not be retrieved or detached.

Behaviors declared in this method will be attached to the component automatically (on demand).

public array behaviors ( )

count() public method #

Returns the number of records.

public integer, string count ( $q = '*', $db = null )

criteriaAttributes() public method #

Returns the query's criteria attributes.

public string[] criteriaAttributes ( )

customFields() protected method #

Returns the fields that should take part in an upcoming elements query.

These fields will get their own criteria parameters in the craft\elements\db\ElementQueryInterface that gets passed in, their field types will each have an opportunity to help build the element query, and their columns in the content table will be selected by the query (for those that have one). If a field has its own column in the content table, but the column name is prefixed with something besides “field_”, make sure you set the columnPrefix attribute on the craft\base\Field, so craft\services\Elements::buildElementsQuery() knows which column to select.

protected craft\base\FieldInterface[] customFields ( )

dateCreated() public method #

Sets the dateCreated() property.

public static dateCreated ( $value )

dateUpdated() public method #

Sets the dateUpdated() property.

public static dateUpdated ( $value )

descendantDist() public method #

Sets the descendantDist() property.

public static descendantDist ( \craft\elements\db\int $value = null )

descendantOf() public method #

Sets the descendantOf() property.

public static descendantOf ( $value )

enabledForSite() public method #

Sets the enabledForSite() property.

public static enabledForSite ( \craft\elements\db\bool $value = true )

fields() public method #

Returns the list of fields that should be returned by default by toArray() when no specific fields are specified.

A field is a named element in the returned array by toArray(). This method should return an array of field names or field definitions. If the former, the field name will be treated as an object property name whose value will be used as the field value. If the latter, the array key should be the field name while the array value should be the corresponding field definition which can be either an object property name or a PHP callable returning the corresponding field value. The signature of the callable should be:

function ($model, $field) {
    // return field value
}

For example, the following code declares four fields:

• email: the field name is the same as the property name email;
• firstName and lastName: the field names are firstName and lastName, and their values are obtained from the first_name and last_name properties;
• fullName: the field name is fullName. Its value is obtained by concatenating first_name and last_name.

return [
    'email',
    'firstName' => 'first_name',
    'lastName' => 'last_name',
    'fullName' => function ($model) {
        return $model->first_name . ' ' . $model->last_name;
    },
];

See also toArray().

public array fields ( )

find() public method #

Deprecated in Craft 3.0. Use all() instead.

Returns all elements that match the criteria.

public craft\base\ElementInterface[] find ( array $attributes = null )

first() public method #

Deprecated in Craft 3.0. Use one() instead.

Returns the first element that matches the criteria.

public craft\base\ElementInterface, null first ( array $attributes = null )

fixedOrder() public method #

Sets the fixedOrder() property.

public static fixedOrder ( \craft\elements\db\bool $value = true )

getCachedResult() public method #

Returns the resulting elements set by setCachedResult(), if the criteria params haven’t changed since then.

See also setCachedResult().

public craft\base\ElementInterface[], null getCachedResult ( )

getCriteria() public method #

Returns an array of the current criteria attribute values.

public array getCriteria ( )

getIterator() public method #

Required by the IteratorAggregate interface.

public ArrayIterator getIterator ( )

id() public method #

Sets the id() property.

public static id ( $value )

ids() public method #

Executes the query and returns the IDs of the resulting elements.

public integer[] ids ( $db = null )

inReverse() public method #

Sets the inReverse() property.

public static inReverse ( \craft\elements\db\bool $value = true )

joinElementTable() protected method #

Joins in a table with an id column that has a foreign key pointing to craft_elements.id.

protected void joinElementTable ( \craft\elements\db\string $table )

last() public method #

Deprecated in Craft 3.0. Use nth() instead.

Returns the last element that matches the criteria.

public craft\base\ElementInterface, null last ( array $attributes = null )

level() public method #

Sets the level() property.

public static level ( $value = null )

locale() public method #

Deprecated in 3.0. Use site() or siteId() instead.

Sets the site() property.

public static locale ( \craft\elements\db\string $value )

localeEnabled() public method #

Deprecated in 3.0. Use enabledForSite() instead.

Sets the enabledForSite() property.

public static localeEnabled ( $value = true )

nextSiblingOf() public method #

Sets the nextSiblingOf() property.

public static nextSiblingOf ( $value )

normalizeOrderBy() protected method #

Normalizes format of ORDER BY data.

protected array normalizeOrderBy ( $columns )

nth() public method #

Executes the query and returns a single row of result at a given offset.

public craft\base\ElementInterface, array, null nth ( \craft\elements\db\int $n, yii\db\Connection $db = null )

offsetExists() public method #

Required by the ArrayAccess interface.

public boolean offsetExists ( $name )

offsetGet() public method #

Required by the ArrayAccess interface.

public mixed offsetGet ( $name )

offsetSet() public method #

Required by the ArrayAccess interface.

public void offsetSet ( $name, $value )

offsetUnset() public method #

Required by the ArrayAccess interface.

public void offsetUnset ( $name )

one() public method #

Executes the query and returns a single row of result.

public craft\base\ElementInterface, array, null one ( $db = null )

order() public method #

Deprecated in Craft 3.0. Use orderBy() instead.

Sets the orderBy() property.

public static order ( \craft\elements\db\string $value )

populate() public method #

Converts the raw query results into the format as specified by this query.

This method is internally used to convert the data fetched from database into the format as required by this query.

public craft\base\ElementInterface[], array populate ( $rows )

positionedAfter() public method #

Sets the positionedAfter() property.

public static positionedAfter ( $value )

positionedBefore() public method #

Sets the positionedBefore() property.

public static positionedBefore ( $value )

prepare() public method #

Prepares for building SQL.

This method is called by \craft\elements\db\QueryBuilder when it starts to build SQL from a query object. You may override this method to do some final preparation work when converting a query into a SQL statement.

public $this prepare ( $builder )

prevSiblingOf() public method #

Sets the prevSiblingOf() property.

public static prevSiblingOf ( $value )

ref() public method #

Sets the ref() property.

public static ref ( $value )

relatedTo() public method #

Sets the relatedTo() property.

public static relatedTo ( $value )

search() public method #

Sets the search() property.

public static search ( $value )

setCachedResult() public method #

Sets the resulting elements.

If this is called, all() will return these elements rather than initiating a new SQL query, as long as none of the parameters have changed since setCachedResult() was called.

See also getCachedResult().

public void setCachedResult ( array $elements )

siblingOf() public method #

Sets the siblingOf() property.

public static siblingOf ( $value )

site() public method #

Sets the siteId() property based on a given site(s)’s handle.

public static site ( $value )

siteId() public method #

Sets the siteId() property.

public static siteId ( \craft\elements\db\int $value = null )

slug() public method #

Sets the slug() property.

public static slug ( $value )

status() public method #

Sets the status() property.

public static status ( $value )

statusCondition() protected method #

Returns the condition that should be applied to the element query for a given status.

For example, if you support a status called “pending”, which maps back to a pending database column that will either be 0 or 1, this method could do this:

protected function statusCondition($status)
{
    switch ($status) {
        case 'pending':
            return ['mytable.pending' => 1];
        default:
            return parent::statusCondition($status);
    }

protected string, array, yii\db\ExpressionInterface, false, null statusCondition ( \craft\elements\db\string $status )

structureId() public method #

Sets the structureId() property.

public static structureId ( \craft\elements\db\int $value = null )

title() public method #

Sets the title() property.

public static title ( $value )

total() public method #

Deprecated in Craft 3.0. Use count() instead.

Returns the total elements that match the criteria.

public integer total ( array $attributes = null )

uid() public method #

Sets the uid() property.

public static uid ( $value )

uri() public method #

Sets the uri() property.

public static uri ( $value )

with() public method #

Sets the with() property.

public self with ( $value )

withStructure() public method #

Sets the withStructure() property.

public static withStructure ( \craft\elements\db\bool $value = true )

Event Details

EVENT_AFTER_POPULATE_ELEMENT event of type craft\events\PopulateElementEvent #

The event that is triggered after an element is populated.

EVENT_AFTER_PREPARE event of type \craft\elements\db\Event #

An event that is triggered at the end of preparing an element query for the query builder.

EVENT_BEFORE_PREPARE event of type \craft\elements\db\Event #

An event that is triggered at the beginning of preparing an element query for the query builder.