DataFilter

API reference › yii › data › DataFilter

class	`yii\data\DataFilter`
Extends	`yii\base\Model` » `yii\base\Component` » `yii\base\BaseObject`
Implements	`yii\base\StaticInstanceInterface`, `IteratorAggregate`, `ArrayAccess`, `yii\base\Arrayable`, `yii\base\Configurable`
Uses traits	`yii\base\ArrayableTrait`, `yii\base\StaticInstanceTrait`
Since	2.0.13
Source	`framework/data/DataFilter.php`

1 subclass

ActiveDataFilter

DataFilter is a special 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 $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 $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 DynamicModel instance as a $searchModel. In this case you should specify $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 $filter value. In order to convert filter to particular format you should use descendant of this class that implements buildInternal() method accordingly.

Properties

Property	Type	Description	Defined by
`$activeValidators` read-only	`yii\validators\Validator[]`	The validators applicable to the current `$scenario`.	`yii\base\Model`
`$attributeMap`	`array`	Actual attribute names to be used in searched condition, in format: [filterAttribute => actualAttribute]. Default: `[]`.	`DataFilter`
`$attributes`	`array<string, mixed>`	Attribute values (name => value).	`yii\base\Model`
`$behaviors` read-only	`array<yii\base\Behavior<static>>`	List of behaviors attached to this component.	`yii\base\Component`
`$conditionValidators`	`array`	Maps filter condition keywords to validation methods. Default: `['AND' => 'validateConjunctionCondition', 'OR' => 'validateConjunctionCondition', 'NOT' => 'validateBlockCondition', '<' => 'validateOperatorCondition', '>' => 'validateOperatorCondition', '<=' => 'validateOperatorCondition', '>=' => 'validateOperatorCondition', '=' => 'validateOperatorCondition', '!=' => 'validateOperatorCondition', 'IN' => 'validateOperatorCondition', 'NOT IN' => 'validateOperatorCondition', 'LIKE' => 'validateOperatorCondition']`.	`DataFilter`
`$errorMessages`	`array\|Closure`	Error messages in `[errorKey => message]` format, or a PHP callback returning them.	`DataFilter`
`$errors` read-only	`array<string, string[]>`	Errors for all attributes.	`yii\base\Model`
`$filter`	`mixed`	Raw filter value.	`DataFilter`
`$filterAttributeLabel`	`string`	Label for the filter attribute specified via `$filterAttributeName`. Default: `null`.	`DataFilter`
`$filterAttributeName`	`string`	Name of the attribute that handles filter value. Default: `'filter'`.	`DataFilter`
`$filterControls`	`array`	Keywords or expressions that could be used in a filter. Default: `['and' => 'AND', 'or' => 'OR', 'not' => 'NOT', 'lt' => '<', 'gt' => '>', 'lte' => '<=', 'gte' => '>=', 'eq' => '=', 'neq' => '!=', 'in' => 'IN', 'nin' => 'NOT IN', 'like' => 'LIKE']`.	`DataFilter`
`$firstErrors` read-only	`array<string, string>`	The first errors.	`yii\base\Model`
`$iterator` read-only	`ArrayIterator<string, mixed>`	An iterator for traversing the items in the list.	`yii\base\Model`
`$multiValueOperators`	`array`	List of operators keywords, which should accept multiple values. Default: `['IN', 'NOT IN']`.	`DataFilter`
`$nullValue`	`string`	Representation of `null` instead of literal `null` in case the latter cannot be used. Default: `'NULL'`. Available since 2.0.40.	`DataFilter`
`$operatorTypes`	`array`	Specifies the list of supported search attribute types per each operator. Default: `['<' => [self::TYPE_INTEGER, self::TYPE_FLOAT, self::TYPE_DATETIME, self::TYPE_DATE, self::TYPE_TIME], '>' => [self::TYPE_INTEGER, self::TYPE_FLOAT, self::TYPE_DATETIME, self::TYPE_DATE, self::TYPE_TIME], '<=' => [self::TYPE_INTEGER, self::TYPE_FLOAT, self::TYPE_DATETIME, self::TYPE_DATE, self::TYPE_TIME], '>=' => [self::TYPE_INTEGER, self::TYPE_FLOAT, self::TYPE_DATETIME, self::TYPE_DATE, self::TYPE_TIME], '=' => '', '!=' => '', 'IN' => '', 'NOT IN' => '', 'LIKE' => [self::TYPE_STRING]]`.	`DataFilter`
`$scenario`	`string`	The scenario that this model is in.	`yii\base\Model`
`$searchAttributeTypes`	`array\|null`	Search attribute type map.	`DataFilter`
`$searchModel`	`yii\base\Model\|array\|string\|callable`	Model instance or its DI compatible configuration.	`DataFilter`
`$validators` read-only	`ArrayObject<int,` `yii\validators\Validator>\|yii\validators\Validator[]`	All the validators declared in the model.	`yii\base\Model`

Methods

Method	Description	Defined by
`__construct()`	Constructor.	`yii\base\BaseObject`
`__call()`	Calls the named method which is not a class method.	`yii\base\Component`
`__clone()`	This method is called after the object is created by cloning an existing one.	`yii\base\Model`
`__get()`	Returns the value of a component property.	`DataFilter`
`__isset()`	Checks if a property is set, i.e. defined and not null.	`DataFilter`
`__set()`	Sets the value of a component property.	`DataFilter`
`__unset()`	Sets a component property to be null.	`DataFilter`
`activeAttributes()`	Returns the attribute names that are subject to validation in the current scenario.	`yii\base\Model`
`addError()`	Adds a new error to the specified attribute.	`yii\base\Model`
`addErrors()`	Adds a list of errors.	`yii\base\Model`
`afterValidate()`	This method is invoked after validation ends.	`yii\base\Model`
`attachBehavior()`	Attaches a behavior to this component.	`yii\base\Component`
`attachBehaviors()`	Attaches a list of behaviors to the component.	`yii\base\Component`
`attributeHints()`	Returns the attribute hints.	`yii\base\Model`
`attributeLabels()`	Returns the attribute labels.	`DataFilter`
`attributes()`	Returns the list of attribute names.	`DataFilter`
`beforeValidate()`	This method is invoked before validation starts.	`yii\base\Model`
`behaviors()`	Returns a list of behaviors that this component should behave as.	`yii\base\Component`
`build()`	Builds actual filter specification form `$filter` value.	`DataFilter`
`canGetProperty()`	Returns a value indicating whether a property can be read.	`DataFilter`
`canSetProperty()`	Returns a value indicating whether a property can be set.	`DataFilter`
`className()` static	Returns the fully qualified name of this class.	`yii\base\BaseObject`
`clearErrors()`	Removes errors for all attributes or a single attribute.	`yii\base\Model`
`createValidators()`	Creates validator objects based on the validation rules specified in `rules()`.	`yii\base\Model`
`detachBehavior()`	Detaches a behavior from the component.	`yii\base\Component`
`detachBehaviors()`	Detaches all behaviors from the component.	`yii\base\Component`
`ensureBehaviors()`	Makes sure that the behaviors declared in `behaviors()` are attached to this component.	`yii\base\Component`
`extraFields()`	Returns the list of fields that can be expanded further and returned by `toArray()`.	`yii\base\ArrayableTrait`
`fields()`	Returns the list of fields that should be returned by default by `toArray()` when no specific fields are specified.	`yii\base\Model`
`formName()`	Returns the form name that this model class should use.	`DataFilter`
`generateAttributeLabel()`	Generates a user friendly attribute label based on the give attribute name.	`yii\base\Model`
`getActiveValidators()`	Returns the validators applicable to the current `$scenario`.	`yii\base\Model`
`getAttributeHint()`	Returns the text hint for the specified attribute.	`yii\base\Model`
`getAttributeLabel()`	Returns the text label for the specified attribute.	`yii\base\Model`
`getAttributes()`	Returns attribute values.	`yii\base\Model`
`getBehavior()`	Returns the named behavior object.	`yii\base\Component`
`getBehaviors()`	Returns all behaviors attached to this component.	`yii\base\Component`
`getErrorMessages()`		`DataFilter`
`getErrors()`	Returns the errors for all attributes or a single attribute.	`yii\base\Model`
`getErrorSummary()`	Returns the errors for all attributes as a one-dimensional array.	`yii\base\Model`
`getFilter()`		`DataFilter`
`getFirstError()`	Returns the first error of the specified attribute.	`yii\base\Model`
`getFirstErrors()`	Returns the first error of every attribute in the model.	`yii\base\Model`
`getIterator()`	Returns an iterator for traversing the attributes in the model.	`yii\base\Model`
`getScenario()`	Returns the scenario that this model is used in.	`yii\base\Model`
`getSearchAttributeTypes()`		`DataFilter`
`getSearchModel()`		`DataFilter`
`getValidators()`	Returns all the validators declared in `rules()`.	`yii\base\Model`
`hasErrors()`	Returns a value indicating whether there is any validation error.	`yii\base\Model`
`hasEventHandlers()`	Returns a value indicating whether there is any handler attached to the named event.	`yii\base\Component`
`hasMethod()`	Returns a value indicating whether a method is defined.	`yii\base\Component`
`hasProperty()`	Returns a value indicating whether a property is defined for this component.	`yii\base\Component`
`init()`	Initializes the object.	`yii\base\BaseObject`
`instance()` static	Returns static class instance, which can be used to obtain meta information.	`yii\base\StaticInstanceTrait`
`isAttributeActive()`	Returns a value indicating whether the attribute is active in the current scenario.	`yii\base\Model`
`isAttributeRequired()`	Returns a value indicating whether the attribute is required.	`yii\base\Model`
`isAttributeSafe()`	Returns a value indicating whether the attribute is safe for massive assignments.	`yii\base\Model`
`load()`	Populates the model with input data.	`yii\base\Model`
`loadMultiple()` static	Populates a set of models with the data from end user.	`yii\base\Model`
`normalize()`	Normalizes filter value, replacing raw keys according to `$filterControls` and `$attributeMap`.	`DataFilter`
`off()`	Detaches an existing event handler from this component.	`yii\base\Component`
`offsetExists()`	Returns whether there is an element at the specified offset.	`yii\base\Model`
`offsetGet()`	Returns the element at the specified offset.	`yii\base\Model`
`offsetSet()`	Sets the element at the specified offset.	`yii\base\Model`
`offsetUnset()`	Sets the element value at the specified offset to null.	`yii\base\Model`
`on()`	Attaches an event handler to an event.	`yii\base\Component`
`onUnsafeAttribute()`	This method is invoked when an unsafe attribute is being massively assigned.	`yii\base\Model`
`rules()`	Returns the validation rules for attributes.	`DataFilter`
`safeAttributes()`	Returns the attribute names that are safe to be massively assigned in the current scenario.	`yii\base\Model`
`scenarios()`	Returns a list of scenarios and the corresponding active attributes.	`yii\base\Model`
`setAttributes()`	Sets the attribute values in a massive way.	`yii\base\Model`
`setErrorMessages()`	Sets the list of error messages responding to invalid filter structure, in format: `[errorKey => message]`.	`DataFilter`
`setFilter()`		`DataFilter`
`setScenario()`	Sets the scenario for the model.	`yii\base\Model`
`setSearchAttributeTypes()`		`DataFilter`
`setSearchModel()`		`DataFilter`
`toArray()`	Converts the model into an array.	`yii\base\ArrayableTrait`
`trigger()`	Triggers an event.	`yii\base\Component`
`validate()`	Performs the data validation.	`yii\base\Model`
`validateFilter()`	Validates filter attribute value to match filer condition specification.	`DataFilter`
`validateMultiple()` static	Validates multiple models.	`yii\base\Model`
`buildInternal()` protected	Performs actual filter build.	`DataFilter`
`defaultErrorMessages()` protected	Returns default values for `$errorMessages`.	`DataFilter`
`detectSearchAttributeType()` protected	Detect attribute type from given validator.	`DataFilter`
`detectSearchAttributeTypes()` protected	Composes default value for `$searchAttributeTypes` from the `$searchModel` validation rules.	`DataFilter`
`extractFieldsFor()` protected	Extract nested fields from a fields collection for a given root field Nested fields are separated with dots (.). e.g: “item.id” The previous example would extract “id”.	`yii\base\ArrayableTrait`
`extractRootFields()` protected	Extracts the root field names from nested fields.	`yii\base\ArrayableTrait`
`filterAttributeValue()` protected	Validates attribute value in the scope of `$searchModel`, applying attribute value filters if any.	`DataFilter`
`parseErrorMessage()` protected	Parses content of the message from `$errorMessages`, specified by message key.	`DataFilter`
`resolveFields()` protected	Determines which fields can be returned by `toArray()`.	`yii\base\ArrayableTrait`
`validateAttributeCondition()` protected	Validates search condition for a particular attribute.	`DataFilter`
`validateAttributeValue()` protected	Validates attribute value in the scope of `Model`.	`DataFilter`
`validateBlockCondition()` protected	Validates block condition that consists of a single condition.	`DataFilter`
`validateCondition()` protected	Validates filter condition.	`DataFilter`
`validateConjunctionCondition()` protected	Validates conjunction condition that consists of multiple independent ones.	`DataFilter`
`validateOperatorCondition()` protected	Validates operator condition.	`DataFilter`

Events

Event	Type	Description	Defined by
`EVENT_BEFORE_VALIDATE`	`yii\base\ModelEvent`	An event raised at the beginning of `validate()`. Event name: `'beforeValidate'`.	`yii\base\Model`
`EVENT_AFTER_VALIDATE`	`yii\base\Event`	An event raised at the end of `validate()` Event name: `'afterValidate'`.	`yii\base\Model`

Constants

Constant	Value	Description	Defined by
`TYPE_INTEGER`	`'integer'`		`DataFilter`
`TYPE_FLOAT`	`'float'`		`DataFilter`
`TYPE_BOOLEAN`	`'boolean'`		`DataFilter`
`TYPE_STRING`	`'string'`		`DataFilter`
`TYPE_ARRAY`	`'array'`		`DataFilter`
`TYPE_DATETIME`	`'datetime'`		`DataFilter`
`TYPE_DATE`	`'date'`		`DataFilter`
`TYPE_TIME`	`'time'`		`DataFilter`
`SCENARIO_DEFAULT`	`'default'`	The name of the default scenario.	`yii\base\Model`

Property details

$attributeMap

public array $attributeMap = []

Actual attribute names to be used in searched condition, in format: [filterAttribute => actualAttribute].

For example, in case of using table joins in the search query, attribute map may look like the following:

[
    'authorName' => '{{author}}.[[name]]'
]

Attribute map will be applied to filter condition in normalize() method.

$conditionValidators

public array $conditionValidators = ['AND' => 'validateConjunctionCondition', 'OR' => 'validateConjunctionCondition', 'NOT' => 'validateBlockCondition', '<' => 'validateOperatorCondition', '>' => 'validateOperatorCondition', '<=' => 'validateOperatorCondition', '>=' => 'validateOperatorCondition', '=' => 'validateOperatorCondition', '!=' => 'validateOperatorCondition', 'IN' => 'validateOperatorCondition', 'NOT IN' => 'validateOperatorCondition', 'LIKE' => 'validateOperatorCondition']

Maps filter condition keywords to validation methods.

These methods are used by validateCondition() to validate raw filter conditions.

$filterAttributeLabel

public string $filterAttributeLabel = null

Label for the filter attribute specified via $filterAttributeName.

It will be used during error messages composition.

$filterAttributeName

public string $filterAttributeName = 'filter'

Name of the attribute that handles filter value.

The name is used to load data via load() method.

$filterControls

public array $filterControls = ['and' => 'AND', 'or' => 'OR', 'not' => 'NOT', 'lt' => '<', 'gt' => '>', 'lte' => '<=', 'gte' => '>=', 'eq' => '=', 'neq' => '!=', 'in' => 'IN', 'nin' => 'NOT IN', 'like' => 'LIKE']

Keywords or expressions that could be used in a filter.

Array keys are the expressions used in raw filter value obtained from user request. Array values are internal build keys used in this class methods.

Any unspecified keyword will not be recognized as a filter control and will be treated as an attribute name. Thus you should avoid conflicts between control keywords and attribute names. For example: in case you have control keyword ‘like’ and an attribute named ‘like’, specifying condition for such attribute will be impossible.

You may specify several keywords for the same filter build key, creating multiple aliases. For example:

[
    'eq' => '=',
    '=' => '=',
    '==' => '=',
    '===' => '=',
    // ...
]

Note: while specifying filter controls take actual data exchange format, which your API uses, in mind. Make sure each specified control keyword is valid for the format. For example, in XML tag name can start only with a letter character, thus controls like >, ’=’ or $gt will break the XML schema.

$operatorTypes

public array $operatorTypes = ['<' => [self::TYPE_INTEGER, self::TYPE_FLOAT, self::TYPE_DATETIME, self::TYPE_DATE, self::TYPE_TIME], '>' => [self::TYPE_INTEGER, self::TYPE_FLOAT, self::TYPE_DATETIME, self::TYPE_DATE, self::TYPE_TIME], '<=' => [self::TYPE_INTEGER, self::TYPE_FLOAT, self::TYPE_DATETIME, self::TYPE_DATE, self::TYPE_TIME], '>=' => [self::TYPE_INTEGER, self::TYPE_FLOAT, self::TYPE_DATETIME, self::TYPE_DATE, self::TYPE_TIME], '=' => '*', '!=' => '*', 'IN' => '*', 'NOT IN' => '*', 'LIKE' => [self::TYPE_STRING]]

Specifies the list of supported search attribute types per each operator.

This field should be in format: ‘operatorKeyword’ => [‘type1’, ‘type2’ …]. Supported types list can be specified as *, which indicates that operator supports all types available. Any unspecified keyword will not be considered as a valid operator.

Method details

__get()

public function __get(mixed $name): mixed

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

Parameters

Parameter	Type	Description
`$name`	`mixed`	The property name

Returns

mixed: The property value or the value of a behavior’s property

Throws

yii\base\UnknownPropertyException: if the property is not defined
yii\base\InvalidCallException: if the property is write-only.

__isset()

public function __isset(mixed $name): bool

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

Parameters

Parameter	Type	Description
`$name`	`mixed`	The property name or the event name

Returns

bool: Whether the named property is set

__set()

public function __set(mixed $name, mixed $value): mixed

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

Parameters

Parameter	Type	Description
`$name`	`mixed`	The property name or the event name
`$value`	`mixed`	The property value

Returns

mixed

Throws

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

__unset()

public function __unset(mixed $name): mixed

Sets a component property to be null.

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

a property defined by a setter: set the property value to be null
a property of a behavior: set the property value to be null

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

Parameters

Parameter	Type	Description
`$name`	`mixed`	The property name

Returns

mixed

Throws

yii\base\InvalidCallException: if the property is read only.

attributeLabels()

public function attributeLabels(): array<string, string>

Returns the attribute labels.

Attribute labels are mainly used for display purpose. For example, given an attribute firstName, we can declare a label First Name which is more user-friendly and can be displayed to end users.

By default an attribute label is generated using generateAttributeLabel(). This method allows you to explicitly specify attribute labels.

Note, in order to inherit labels defined in the parent class, a child class needs to merge the parent labels with child labels using functions such as array_merge().

Returns

array<string, string>: Attribute labels (name => label)

attributes()

public function attributes(): string[]

Returns the list of attribute names.

By default, this method returns all public non-static properties of the class. You may override this method to change the default behavior.

Returns

string[]: List of attribute names.

build()

public function build(bool $runValidation = true): mixed|false

Builds actual filter specification form $filter value.

Parameters

Parameter	Type	Description
`$runValidation`	`bool`	Whether to perform validation (calling `validate()`) before building the filter. Defaults to `true`. If the validation fails, no filter will be built and this method will return `false`.

Returns

mixed|false: Built actual filter value, or false if validation fails.

canGetProperty()

public function canGetProperty(mixed $name, mixed $checkVars = true, mixed $checkBehaviors = true): bool

Returns a value indicating whether a property can be read.

A property can be read if:

the class has a getter method associated with the specified name (in this case, property name is case-insensitive);
the class has a member variable with the specified name (when $checkVars is true);
an attached behavior has a readable property of the given name (when $checkBehaviors is true).

Parameters

Parameter	Type	Description
`$name`	`mixed`	The property name
`$checkVars`	`mixed`	Whether to treat member variables as properties
`$checkBehaviors`	`mixed`	Whether to treat behaviors’ properties as properties of this component

Returns

bool: Whether the property can be read

canSetProperty()

public function canSetProperty(mixed $name, mixed $checkVars = true, mixed $checkBehaviors = true): bool

Returns a value indicating whether a property can be set.

A property can be written if:

the class has a setter method associated with the specified name (in this case, property name is case-insensitive);
the class has a member variable with the specified name (when $checkVars is true);
an attached behavior has a writable property of the given name (when $checkBehaviors is true).

Parameters

Parameter	Type	Description
`$name`	`mixed`	The property name
`$checkVars`	`mixed`	Whether to treat member variables as properties
`$checkBehaviors`	`mixed`	Whether to treat behaviors’ properties as properties of this component

Returns

bool: Whether the property can be written

formName()

public function formName(): string

Returns the form name that this model class should use.

The form name is mainly used by ActiveForm to determine how to name the input fields for the attributes in a model. If the form name is “A” and an attribute name is “b”, then the corresponding input name would be “A[b]”. If the form name is an empty string, then the input name would be “b”.

The purpose of the above naming schema is that for forms which contain multiple different models, the attributes of each model are grouped in sub-arrays of the POST-data and it is easier to differentiate between them.

By default, this method returns the model class name (without the namespace part) as the form name. You may override it when the model is used in different forms.

Returns

string: The form name of this model class.

Throws

yii\base\InvalidConfigException: when form is defined with anonymous class and formName() method is not overridden.

getErrorMessages()

public function getErrorMessages(): array

Returns

array: Error messages in format [errorKey => message].

getFilter()

public function getFilter(): mixed

Returns

mixed: Raw filter value.

getSearchAttributeTypes()

public function getSearchAttributeTypes(): array

Returns

array: Search attribute type map.

getSearchModel()

public function getSearchModel(): yii\base\Model

Returns

yii\base\Model: Model instance.

Throws

yii\base\InvalidConfigException: on invalid configuration.

normalize()

public function normalize(bool $runValidation = true): array|bool

Normalizes filter value, replacing raw keys according to $filterControls and $attributeMap.

Parameters

Parameter	Type	Description
`$runValidation`	`bool`	Whether to perform validation (calling `validate()`) before normalizing the filter. Defaults to `true`. If the validation fails, no filter will be processed and this method will return `false`.

Returns

array|bool: Normalized filter value, or false if validation fails.

rules()

public function rules(): array<int, array<array-key, mixed>|yii\validators\Validator>

Returns the validation rules for attributes.

Validation rules are used by validate() to check if attribute values are valid. Child classes may override this method to declare different validation rules.

Each rule is an array with the following structure:

[
    ['attribute1', 'attribute2'],
    'validator type',
    'on' => ['scenario1', 'scenario2'],
    //...other parameters...
]

where

attribute list: required, specifies the attributes array to be validated, for single attribute you can pass a string;
validator type: required, specifies the validator to be used. It can be a built-in validator name, a method name of the model class, an anonymous function, or a validator class name.
on: optional, specifies the scenarios array in which the validation rule can be applied. If this option is not set, the rule will apply to all scenarios.
additional name-value pairs can be specified to initialize the corresponding validator properties. Please refer to individual validator class API for possible properties.

A validator can be either an object of a class extending Validator, or a model class method (called inline validator) that has the following signature:

// $params refers to validation parameters given in the rule
function validatorName($attribute, $params)

In the above $attribute refers to the attribute currently being validated while $params contains an array of validator configuration options such as max in case of string validator. The value of the attribute currently being validated can be accessed as $this->$attribute. Note the $ before attribute; this is taking the value of the variable $attribute and using it as the name of the property to access.

Yii also provides a set of built-in validators. Each one has an alias name which can be used when specifying a validation rule.

Below are some examples:

[
    // built-in "required" validator
    [['username', 'password'], 'required'],
    // built-in "string" validator customized with "min" and "max" properties
    ['username', 'string', 'min' => 3, 'max' => 12],
    // built-in "compare" validator that is used in "register" scenario only
    ['password', 'compare', 'compareAttribute' => 'password2', 'on' => 'register'],
    // an inline validator defined via the "authenticate()" method in the model class
    ['password', 'authenticate', 'on' => 'login'],
    // a validator of class "DateRangeValidator"
    ['dateRange', 'DateRangeValidator'],
];

Note, in order to inherit rules defined in the parent class, a child class needs to merge the parent rules with child rules using functions such as array_merge().

Returns

array<int, array<array-key, mixed>|yii\validators\Validator>: Validation rules

setErrorMessages()

public function setErrorMessages(array|Closure $errorMessages): mixed

Sets the list of error messages responding to invalid filter structure, in format: [errorKey => message].

Message may contain placeholders that will be populated depending on the message context. For each message a {filter} placeholder is available referring to the label for $filterAttributeName attribute.

Parameters

Parameter	Type	Description
`$errorMessages`	`array\|Closure`	Error messages in `[errorKey => message]` format, or a PHP callback returning them.

Returns

mixed

setFilter()

public function setFilter(mixed $filter): mixed

Parameters

Parameter	Type	Description
`$filter`	`mixed`	Raw filter value.

Returns

mixed

setSearchAttributeTypes()

public function setSearchAttributeTypes(array|null $searchAttributeTypes): mixed

Parameters

Parameter	Type	Description
`$searchAttributeTypes`	`array\|null`	Search attribute type map.

Returns

mixed

setSearchModel()

public function setSearchModel(yii\base\Model|array|string|callable $model): mixed

Parameters

Parameter	Type	Description
`$model`	`yii\base\Model\|array\|string\|callable`	Model instance or its DI compatible configuration.

Returns

mixed

Throws

yii\base\InvalidConfigException: on invalid configuration.

validateFilter()

public function validateFilter(): mixed

Validates filter attribute value to match filer condition specification.

Returns

mixed

buildInternal()

protected function buildInternal(): mixed

Performs actual filter build.

By default this method returns result of normalize(). The child class may override this method providing more specific implementation.

Returns

mixed: Built actual filter value.

defaultErrorMessages()

protected function defaultErrorMessages(): array

Returns default values for $errorMessages.

Returns

array: Default error messages in [errorKey => message] format.

detectSearchAttributeType()

protected function detectSearchAttributeType(yii\validators\Validator $validator): string|null

Detect attribute type from given validator.

Parameters

Parameter	Type	Description
`$validator`	`yii\validators\Validator`	Validator from which to detect attribute type.

Returns

string|null: Detected attribute type.

Since

2.0.14

detectSearchAttributeTypes()

protected function detectSearchAttributeTypes(): array

Composes default value for $searchAttributeTypes from the $searchModel validation rules.

Returns

array: Attribute type map.

filterAttributeValue()

protected function filterAttributeValue(string $attribute, mixed $value): mixed

Validates attribute value in the scope of $searchModel, applying attribute value filters if any.

Parameters

Parameter	Type	Description
`$attribute`	`string`	Attribute name.
`$value`	`mixed`	Attribute value.

Returns

mixed: Filtered attribute value.

parseErrorMessage()

protected function parseErrorMessage(string $messageKey, array $params = []): string

Parses content of the message from $errorMessages, specified by message key.

Parameters

Parameter	Type	Description
`$messageKey`	`string`	Message key.
`$params`	`array`	Params to be parsed into the message.

Returns

string: Composed message string.

validateAttributeCondition()

protected function validateAttributeCondition(string $attribute, mixed $condition): mixed

Validates search condition for a particular attribute.

Parameters

Parameter	Type	Description
`$attribute`	`string`	Search attribute name.
`$condition`	`mixed`	Search condition.

Returns

mixed

validateAttributeValue()

protected function validateAttributeValue(string $attribute, mixed $value): mixed

Validates attribute value in the scope of Model.

Parameters

Parameter	Type	Description
`$attribute`	`string`	Attribute name.
`$value`	`mixed`	Attribute value.

Returns

mixed

validateBlockCondition()

protected function validateBlockCondition(string $operator, mixed $condition): mixed

Validates block condition that consists of a single condition.

This covers such operators as not.

Parameters

Parameter	Type	Description
`$operator`	`string`	Raw operator control keyword.
`$condition`	`mixed`	Raw condition.

Returns

mixed

validateCondition()

protected function validateCondition(mixed $condition): mixed

Validates filter condition.

Parameters

Parameter	Type	Description
`$condition`	`mixed`	Raw filter condition.

Returns

mixed

validateConjunctionCondition()

protected function validateConjunctionCondition(string $operator, mixed $condition): mixed

Validates conjunction condition that consists of multiple independent ones.

This covers such operators as and and or.

Parameters

Parameter	Type	Description
`$operator`	`string`	Raw operator control keyword.
`$condition`	`mixed`	Raw condition.

Returns

mixed

validateOperatorCondition()

protected function validateOperatorCondition(string $operator, mixed $condition, string|null $attribute = null): mixed

Validates operator condition.

Parameters

Parameter	Type	Description
`$operator`	`string`	Raw operator control keyword.
`$condition`	`mixed`	Attribute condition.
`$attribute`	`string\|null`	Attribute name.

Returns

mixed