Class yii\data\DataFilter

DataFilter is a special yii\base\Model for processing query filtering specification.

It allows validating and building a filter condition passed via request.

Filter example:

{
    "or": [
        {
            "and": [
                {
                    "name": "some name",
                },
                {
                    "price": "25",
                }
            ]
        },
        {
            "id": {"in": [2, 5, 9]},
            "price": {
                "gt": 10,
                "lt": 50
            }
        }
    ]
}

In the request the filter should be specified using a key name equal to $filterAttributeName. Thus actual HTTP request body will look like following:

{
    "filter": {"or": {...}},
    "page": 2,
    ...
}

Raw filter value should be assigned to \yii\data\filter property of the model. You may populate it from request data via load() method:

use yii\data\DataFilter;

$dataFilter = new DataFilter();
$dataFilter->load(Yii::$app->request->getBodyParams());

In order to function this class requires a search model specified via \yii\data\searchModel. This search model should declare all available search attributes and their validation rules. For example:

class SearchModel extends \yii\base\Model
{
    public $id;
    public $name;

    public function rules()
    {
        return [
            [['id', 'name'], 'trim'],
            ['id', 'integer'],
            ['name', 'string'],
        ];
    }
}

In order to reduce amount of classes, you may use yii\base\DynamicModel instance as a \yii\data\searchModel. In this case you should specify \yii\data\searchModel using a PHP callable:

function () {
    return (new \yii\base\DynamicModel(['id' => null, 'name' => null]))
        ->addRule(['id', 'name'], 'trim')
        ->addRule('id', 'integer')
        ->addRule('name', 'string');
}

You can use validate() method to check if filter value is valid. If validation fails you can use getErrors() to get actual error messages.

In order to acquire filter condition suitable for fetching data use build() method.

Note: This is a base class. Its implementation of build() simply returns normalized \yii\data\filter value. In order to convert filter to particular format you should use descendant of this class that implements buildInternal() method accordingly.

See also yii\data\ActiveDataFilter.