Fix for #4479 REST filter

[klimov-paul]

Q	A
Is bugfix?	no
New feature?	yes
Breaks BC?	no
Tests pass?	yes
Fixed issues	#4479

Implemented REST filter.
Format inspired from the ones used by ElasticSearch and MongoDB.

[klimov-paul]

Added support for request via body content at IndexAction.
For the test you can use command like following:

curl -XGET http://domain.com/api/item?_format=json -H content-type:application/json -d '{"filter":{"id": 1}}'

[samdark]

Is there a reason to use $ in keys?

[klimov-paul]

Is there a reason to use $ in keys?

This is a practice borrowed from ElasticSearch and MongoDB. In particular I can provide following reasons:

• keywords with $ are unlikely to be missplaced for a search attribute or value: and, eq, lte and so on can be names of attribute or actual values.
• keys with $ are easy to notice while reading the filter in JSON format
• JSON documents can be automatically sorted by some reading tools (firebug console, for example), using $ ensures keywords will appear at the top.

[klimov-paul]

Is there a reason to use $ in keys?

Also note that all operators are configurable: you can change thier keywords to whatever you like.

[samdark]

Yes, I've noticed that. I'm concerned about defaults.

[niksamokhvalov]

A good format. It seems to abandon the $ of the impossible, though the format and complicated. This symbol needs to clearly define the terms and and or.

Here's what I don't like: applications, simultaneously, using forms and REST API for the same model, will have to make several implementations of the filters (searchModel and dataFilter models). In fact, we want to implement the same behavior, but we still need to write it twice.

[klimov-paul]

will have to make several implementations of the filters (searchModel and dataFilter models). In fact, we want to implement the same behavior, but we still need to write it twice.

You can reuse a search model created for the regular 'frontend' listing in REST even without this fix via IndexAction::prepareDataProvider:

class SearchModel extends \yii\base\Model
{
    // ...

    public function search($params, $formName = null)
    {
        $query = Item::find();

        // add conditions that should always apply here

        $dataProvider = new ActiveDataProvider([
            'query' => $query,
        ]);

        $this->load($params, $formName); // remember that you can pass `formName` directly to the `load()` method

        if (!$this->validate()) {
            $query->where('0=1');
            return $formName === '' ? $this : $dataProvider;
        }
    }

class ItemController extends \yii\rest\ActiveController
{

    // ...

    public function actions()
    {
        return [
            'index' => [
                'class' => 'yii\rest\IndexAction',
                'modelClass' => $this->modelClass,
                'prepareDataProvider' => function () {
                    $searchModel = new SearchModel();
                    return $searchModel->search(Yii::$app->request->queryParams, '');
                },
            ],
        ];
    }

With such code: search at the regular 'frontend' will be performed via following URL:

domain.com/items?ItemSearch[name]=foo&ItemSearch[status]=1

while for the REST - URL will be following:

domain.com/api/items?name=foo&status=1

There is no need to change something to implement simpliest search in the REST. I have alreay told this here:
#4479 (comment)

This PR introduces sophisticated search condition builder, which can be used for creating 'database-like' search interface.
It may be useful in case you are splitting your application into a mirco services, which interact with each other via REST.

[tunecino]

@klimov-paul shouldn't that SearchModel replace the old one here ? also what do you think about adding an interface for it ? (see related discussion in #11470)

[klimov-paul]

shouldn't that SearchModel replace the old one here ?

Unlikely, because it more complex and thus will confuse newcomers.
You can create your own Gii CRUD template, if you want to use it by default.

what do you think about adding an interface for it ?

I am unsure if search interface can be made generic enough. It still may need extra options.

[klimov-paul]

Refactored:

• Extracted DataFilter::$filterControls allowing setup of control keywords to be used in filter.
• Added DataFilter::$attributeMap supporting table joins
• Added I18N for error messages

[SilverFire]

Could be moved to the condition above.

[klimov-paul]

No, it could not: $model may be an array or string class name, which is a valid value and should not throw an exception.

[SilverFire]

$model may be an array

Then it will not be object and no exception will be thrown

[klimov-paul]

fixed

[SilverFire]

I'd move this part to a separate protected method to make it easier to adjust for custom validators.

[klimov-paul]

Disagreed.
It is meant to override a whole detectSearchAttributeTypes() ot provide some sophosticated type detecttion mechanism. Particular implementation may not process validators at all.

[SilverFire]

Adding custom validator does not lead to any sophisticated type detection logic. It is still a map: class to type. I don't think that overriding the whole method (including logic) is a right way for filter configuration.

Moreover, current approach increases formal cyclomatic complexity.

[klimov-paul]

Repeat once more: method detectSearchAttributeTypes() as a whole determines the search attribute types. The actual algorithm of its detection may be different.
For example: you may want to get types from DB table schema, or may want to parse PHPDoc searching for type-hints.
It is only a single particular implementation, which relies on model validators.

If I add extra method for validators processing, it will become useless and never will be invoked in case detectSearchAttributeTypes() rewritten to use DB table schema.

I don't think that overriding the whole method (including logic) is a right way for filter configuration.

How is method override related to filter configuration? You can set $searchAttributeTypes via setSearchAttributeTypes() to whatever you like. Method detectSearchAttributeTypes() invoked only in case there are $searchAttributeTypes explicitly configured.

[SilverFire]

array|\Closure

[klimov-paul]

fixed

[samdark]

Code and user API looks good to me. @klimov-paul should it be described in the guide?

[klimov-paul]

should it be described in the guide?

Extra docs will not hurt. But I can not afford to waste any more time on this.
If you suppose guide section to be essential - someone else should take care of it.

[samdark]

OK.

[samdark]

@yiisoft/reviewers need your help to:

1. Ensure overall code is good. I think it is but I could be wrong.
2. Ensure phpdoc is clear.
3. Ensure English in phpdoc is OK.

Thanks.

[SilverFire]

Good otherwise

[SilverFire]

2.0.13

[samdark]

Merged. Thanks for solving it.

[samdark]

Docs will be handled separately but for 2.0.13 as well.