Trait yii\db\ActiveQueryTrait

All Classes | Properties | Methods

Implemented by	yii\db\ActiveQuery, yii\elasticsearch\ActiveQuery, yii\mongodb\ActiveQuery, yii\mongodb\file\ActiveQuery, yii\redis\ActiveQuery, yii\sphinx\ActiveQuery
Available since version	2.0
Source Code	https://github.com/yiisoft/yii2/blob/master/framework/db/ActiveQueryTrait.php

ActiveQueryTrait implements the common methods and properties for active record query classes.

Public Properties

Hide inherited properties

Property	Type	Description	Defined By
$asArray	boolean	Whether to return each record as an array.	yii\db\ActiveQueryTrait
$modelClass	string	The name of the ActiveRecord class.	yii\db\ActiveQueryTrait
$with	array	A list of relations that this query should be performed with	yii\db\ActiveQueryTrait

Public Methods

Hide inherited methods

Method	Description	Defined By
asArray()	Sets the asArray() property.	yii\db\ActiveQueryTrait
findWith()	Finds records corresponding to one or multiple relations and populates them into the primary models.	yii\db\ActiveQueryTrait
with()	Specifies the relations with which this query should be performed.	yii\db\ActiveQueryTrait

Protected Methods

Hide inherited methods

Method	Description	Defined By
createModels()	Converts found rows into model instances.	yii\db\ActiveQueryTrait

Property Details

Hide inherited properties

$asArray public property

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

public boolean $asArray = null

$modelClass public property

The name of the ActiveRecord class.

public string $modelClass = null

$with public property

A list of relations that this query should be performed with

public array $with = null

Method Details

Hide inherited methods

asArray() public method

Sets the asArray() property.

public $this asArray ( $value = true )
$value	boolean	Whether to return the query results in terms of arrays instead of Active Records.
return	$this	The query object itself

Source code

                public function asArray($value = true)
{
    $this->asArray = $value;
    return $this;
}

createModels() protected method (available since version 2.0.11)

Converts found rows into model instances.

protected array\|yii\db\ActiveRecord[] createModels ( $rows )
$rows	array

Source code

                protected function createModels($rows)
{
    if ($this->asArray) {
        return $rows;
    } else {
        $models = [];
        /* @var $class ActiveRecord */
        $class = $this->modelClass;
        foreach ($rows as $row) {
            $model = $class::instantiate($row);
            $modelClass = get_class($model);
            $modelClass::populateRecord($model, $row);
            $models[] = $model;
        }
        return $models;
    }
}

findWith() public method

Finds records corresponding to one or multiple relations and populates them into the primary models.

public void findWith ( $with, &$models )
$with	array	A list of relations that this query should be performed with. Please refer to with() for details about specifying this parameter.
$models	array\|yii\db\ActiveRecord[]	The primary models (can be either AR instances or arrays)

Source code

                public function findWith($with, &$models)
{
    if (empty($models)) {
        return;
    }
    $primaryModel = reset($models);
    if (!$primaryModel instanceof ActiveRecordInterface) {
        /* @var $modelClass ActiveRecordInterface */
        $modelClass = $this->modelClass;
        $primaryModel = $modelClass::instance();
    }
    $relations = $this->normalizeRelations($primaryModel, $with);
    /* @var $relation ActiveQuery */
    foreach ($relations as $name => $relation) {
        if ($relation->asArray === null) {
            // inherit asArray from primary query
            $relation->asArray($this->asArray);
        }
        $relation->populateRelation($name, $models);
    }
}

with() public method

Specifies the relations with which this query should be performed.

The parameters to this method can be either one or multiple strings, or a single array of relation names and the optional callbacks to customize the relations.

A relation name can refer to a relation defined in $modelClass or a sub-relation that stands for a relation of a related record. For example, orders.address means the address relation defined in the model class corresponding to the orders relation.

The following are some usage examples:

// find customers together with their orders and country
Customer::find()->with('orders', 'country')->all();
// find customers together with their orders and the orders' shipping address
Customer::find()->with('orders.address')->all();
// find customers together with their country and orders of status 1
Customer::find()->with([
    'orders' => function (\yii\db\ActiveQuery $query) {
        $query->andWhere('status = 1');
    },
    'country',
])->all();

You can call with() multiple times. Each call will add relations to the existing ones. For example, the following two statements are equivalent:

Customer::find()->with('orders', 'country')->all();
Customer::find()->with('orders')->with('country')->all();

public $this with ( )
return	$this	The query object itself

Source code

                public function with()
{
    $with = func_get_args();
    if (isset($with[0]) && is_array($with[0])) {
        // the parameter is given as an array
        $with = $with[0];
    }
    if (empty($this->with)) {
        $this->with = $with;
    } elseif (!empty($with)) {
        foreach ($with as $name => $value) {
            if (is_int($name)) {
                // repeating relation is fine as normalizeRelations() handle it well
                $this->with[] = $value;
            } else {
                $this->with[$name] = $value;
            }
        }
    }
    return $this;
}