Yii2 : ActiveQuery Example and what is the reason to generate ActiveQuery class separately in Gii?

Could you provide an example usage. Description will be highly appreciated. I can not find a good example for it.

The Active Query represents a DB query associated with an Active Record class. It is usually used to override the default find() method of a specific model where it will be used to generate the query before sending to DB :

class OrderQuery extends ActiveQuery
{
     public function payed()
     {
        return $this->andWhere(['status' => 1]);
     }

     public function big($threshold = 100)
     {
        return $this->andWhere(['>', 'subtotal', $threshold]);
     }

}

If you worked before with Yii 1 then this is what replaces Yii 1.x Named Scopes in Yii2. All you have to do is to override the find() method in your model class to use the ActiveQuery class above :

// This will be auto generated by gii if 'Generate ActiveQuery' is selected
public static function find()
{
    return new \app\models\OrderQuery(get_called_class());
}

Then you can use it this way :

$payed_orders      =   Order::find()->payed()->all();

$very_big_orders   =   Order::find()->big(999)->all();

$big_payed_orders  =   Order::find()->big()->payed()->all();

---

A different use case of the same ActiveQuery class defined above is by using it when defining relational data in a related model class like:

class Customer extends \yii\db\ActiveRecord
{
    ...

    public function getPayedOrders()
    {
        return $this->hasMany(Order::className(),['customer_id' => 'id'])->payed();
    }
}

Then you can eager load customers with their respective payed orders by doing :

$customers = Customer::find()->with('payedOrders')->all();