Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yii2tech/ar-search
Provides unified search model for Yii ActiveRecord
https://github.com/yii2tech/ar-search
activerecord filter filtering search yii yii2 yii2-extension
Last synced: 6 days ago
JSON representation
Provides unified search model for Yii ActiveRecord
- Host: GitHub
- URL: https://github.com/yii2tech/ar-search
- Owner: yii2tech
- License: other
- Archived: true
- Created: 2016-10-13T08:35:50.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2020-03-04T11:20:08.000Z (almost 5 years ago)
- Last Synced: 2025-01-14T08:58:48.491Z (13 days ago)
- Topics: activerecord, filter, filtering, search, yii, yii2, yii2-extension
- Language: PHP
- Homepage:
- Size: 30.3 KB
- Stars: 31
- Watchers: 7
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
ActiveRecord Search Model Extension for Yii2
This extension provides unified search model for Yii ActiveRecord.
For license information check the [LICENSE](LICENSE.md)-file.
[](https://packagist.org/packages/yii2tech/ar-search)
[](https://packagist.org/packages/yii2tech/ar-search)
[](https://travis-ci.org/yii2tech/ar-search)
Installation
------------
The preferred way to install this extension is through [composer](http://getcomposer.org/download/).
Either run
```
php composer.phar require --prefer-dist yii2tech/ar-search
```
or add
```json
"yii2tech/ar-search": "*"
```
to the require section of your composer.json.
Usage
-----
This extension provides unified search model for Yii ActiveRecord via special model class -
`\yii2tech\ar\search\ActiveSearchModel`.
This model is able to fetch its attributes, validation rules and filtering logic from the 'slave'
source ActiveRecord model specified via `\yii2tech\ar\search\ActiveSearchModel::$model`.
Thus you do not need to declare a separated model class for searching and define a filter logic.
For example:
```php
'app\models\Item'
]);
$dataProvider = $searchModel->search(Yii::$app->request->queryParams);
```
`ActiveSearchModel` picks all 'safe' attributes of the 'slave' model and use them as own attributes.
Thus you can use any attribute, which is marked as 'safe' in related ActiveRecord model in the scope
of this class. For example:
```php
'app\models\Item'
]);
// safe attributes of `Item` are inherited:
$searchModel->name = 'Paul';
$searchModel->price = 10.5;
```
Inherited attributes may be used while composing web forms, which should collect filter data.
For example:
```php
'app\models\Item'
]);
?>
= $form->field($model, 'name')->textInput() ?>
= $form->field($model, 'price')->textInput() ?>
...
```
Attribute labels and hints are also inherited from the 'slave' model.
The main method of `\yii2tech\ar\search\ActiveSearchModel` is `search()`. It loads filter attributes
from given data array, validates them an creates a `\yii\data\ActiveDataProvider` instance applying
own attributes as a query filter condition.
`ActiveSearchModel` uses a sophisticated logic for the query filtering, based on the attribute types,
specified by `\yii2tech\ar\search\ActiveSearchModel::$searchAttributeTypes`, which value is extracted
from `\yii2tech\ar\search\ActiveSearchModel::$model` by default and filter operators list, specified via
`\yii2tech\ar\search\ActiveSearchModel::$filterOperators`.
By default `\yii\db\QueryInterface::andFilterWhere()` will be used for the filter composition. For the
'string' attributes it will be used with 'like' operator. For 'integer' and 'float' ('double') method
`andFilterCompare()` will be used, if it is available.
**Heads up!** Do not abuse `ActiveSearchModel` usage. It has been designed to cover only the simplest
cases, when search logic is trivial. You should always create a separated search model in case, it
requires complex logic of composition of the search query.
## Adjusting Data Provider
You may want to change some settings of the data provider, created by the `search()` method: change
pagination or sort settings and so on. You can do this via `\yii2tech\ar\search\ActiveSearchModel::$dataProvider`.
For example:
```php
'app\models\Item',
'dataProvider' => [
'class' => 'yii\data\ActiveDataProvider',
'pagination' => [
'defaultPageSize' => 40
],
],
]);
$dataProvider = $searchModel->search(Yii::$app->request->queryParams);
echo $dataProvider->pagination->defaultPageSize; // outputs `40`
```
## Adjusting Search Query
You may use `\yii2tech\ar\search\ActiveSearchModel::EVENT_AFTER_CREATE_QUERY` event to adjust the search query instance
adding relation eager loading or permanent conditions. For example:
```php
'app\models\Item',
]);
$searchModel->on(ActiveSearchModel::EVENT_AFTER_CREATE_QUERY, function(ActiveSearchEvent $event) {
$event->query
->with(['category'])
->andWhere(['status' => 1]);
});
```
You may also specify query object directly via `\yii2tech\ar\search\ActiveSearchModel::$dataProvider`. For example:
```php
Item::className(),
'dataProvider' => function () {
$query = Item::find()
->with(['category'])
->andWhere(['status' => 1]);
return ActiveDataProvider(['query' => $query]);
},
]);
```
## Filter Operators
You can control the operators to be used for the query filtering via `\yii2tech\ar\search\ActiveSearchModel::$filterOperators`.
It defines a mapping between the attribute type and the operator to be used with `\yii\db\QueryInterface::andFilterWhere()`.
Each value can be a scalar operator name or a PHP callback, accepting query instance, attribute name and value.
For example:
```php
'app\models\Item',
'filterOperators' => [
ActiveSearchModel::TYPE_STRING => '=', // use strict comparison for the string attributes
ActiveSearchModel::TYPE_INTEGER => function (\yii\db\ActiveQueryInterface $query, $attribute, $value) {
if ($attribute === 'commentsCount') {
$query->andHaving(['commentsCount' => $value]);
} else {
$query->andFilterWhere([$attribute => $value]);
}
},
],
]);
```
`ActiveSearchModel` allows filtering for the attributes using `andFilterCompare()` method of the query (for example:
`\yii\db\Query::andFilterCompare()`), which allows specifying filter value in format: `{operator}{value}` (for
example: `>10`, `<=100` and so on). The list of attribute names, for which usage of such comparison is allowed is controlled
by `\yii2tech\ar\search\ActiveSearchModel::$compareAllowedAttributes`. For example:
```php
'app\models\Item',
'compareAllowedAttributes' => [
'price' // allow compare for 'price' only, excluding such fields like 'categoryId', 'status' and so on.
],
]);
```
You can set `compareAllowedAttributes` to `*`, which indicates any float or integer attribute will be allowed for comparison.
> Note: `\yii2tech\ar\search\ActiveSearchModel::$filterOperators` take precedence over `\yii2tech\ar\search\ActiveSearchModel::$compareAllowedAttributes`.
## Working Without 'Slave' Model
Although in most cases setup of `\yii2tech\ar\search\ActiveSearchModel::$model` is a quickest way to configure `ActiveSearchModel`
instance, it is not mandatory. You can avoid setup of the 'slave' model and configure all search related properties
directly. For example:
```php
[
'id' => ActiveSearchModel::TYPE_INTEGER,
'name' => ActiveSearchModel::TYPE_STRING,
'price' => ActiveSearchModel::TYPE_FLOAT,
],
'rules' => [
['id', 'integer'],
['name', 'string'],
['price', 'number'],
],
'compareAllowedAttributes' => [],
'dataProvider' => function () {
$query = Item::find()
->with(['category'])
->andWhere(['status' => 1]);
return ActiveDataProvider(['query' => $query]);
},
]);
```