Download the PHP package yurenery/sextant without Composer

Laravel Sextant.

Laravel Sextant - this is powerful, smart and simple filtration engine for api calls for laravel.

Capability Tale:

Installation

• add below code into composer.json:

• Publish configuration:

Basics

Use HasSextantOperations trait in the model. Redeclare extraFields() function if you need to make some relations publicly accessible for the api calls. Use below example:

By default, after using sextant trait, it connects to the model as scope operation. So you can call it as below:

Filter Usage

You must use $_GET parameter called filter to interacts with model filtering. Filter parameter expects json string with parameters.

Available operations:

isNull - not required parameter parameter, accept true or false, add AND $key IS NULL or AND $key IS NOT NULL to sql query string

operation - is a logical operation identifier, accept '>','<','>=','<=','<>','not in','in','like'.

value - sample value, can be array, if "operation":"in" or "operation":"not in" used.

from и to - range filtration operations. Can work stand alone. If fates received, they processed as dates by Carbon::parse() function and converted to mysql format. For filtration we use >= и <=, so values from and to included into range too. In situations, where operations <= and >= not allowed - you can use your own filtration. Example - {"from": { "value": "123","operation":">"}}.

NOTE: For simple equals query, use simple notation - {"id":1}, then query will have a look as WHERE id = 1.

Query examples:

Filtrate models by relations existence:

Filtrate by relations:

You myst define allowed relations into extraFields function. Use relations filters same as with simple fields in the root model.

Filtrate relations

You can filtrate relations by using $_GET parameter filterExpand. It works same as simple filter, but filtrate relation data.

After that, if you send in request any filtration operations or sorting, or expand - given relation will be skipped. NOTE: 'only' restriction also works with empty array - ['only' => ['expand' => []]] - will disallow any expands and filtration operations on them on given request.

Sorting

You can sort data by any model or relations fields. To use sorting just define $_GET parameter called sort. Sextant sort by default as asc, if you need desc sorting - you need to add minus sign in sort definition prefix. Example - -views_count

Sorting examples:

You can define multiple sorting, just separate sort string with commas. Example -?sort=user.first_name,user.last_name

Relations sorting

You can sort relation. Use $_GET parameter sortExpand. It works same as simple sorting on root model, but sorts relation data.

Relation expands

You can request relation expand. You can request allowed by extraFields() relations only. Add $_GET parameter called expand to the request. NOTE: Not allowed relations will be ignored. Parameter expand required for filterExpand and sortExpand operations.

Expand examples:

response example:

Restrictions

Since 1.1.4 version you can provide restrictions for filter operations. For example, we have a goal to disable some expands on index method of our CRUD to achieve full protection of speed, then we can use restrictions:

Searching

For short sql like search was added search parameter. This parameter works with root model and any relations fields.

Searching example:

Laravel scopes usage.

In Sextant you can user native laravel scope functionality. Working with scopes is simple as filtering:

NOTE: If working with relations - scope must be present in relation model. You can simply connect scope to the request. Just user it like below:

You must pass parameters key, when using scopes directive, even if parameters are empty. To protect models scopes from not allowed requests use extraScopes() function. For example:

!!!NOTE: Using scopes for open world brings a lot of protection issues. You can create orWhere queries or etc, which will break your protection of search. To avoid that:

This code will convert into SQL:

Raw usage

You can use Sextant without model calls or on models that does not use Sextant operations trait. For example:

As you can see, you can use filtration on model class. If model does not have Sextant operations, we will user our default model, which we will convert into yours:

NOTE: that default models has empty extraFields and extraScopes. NOTE: that you can pre-define parameters for filtration by passing third parameter into ->withSextant(...) function. Just pass parameters as array. Example:

Extensions

You can create your own extensions for Sextant engine. Just add your new action into config. NOTE: Every new action must implement Amondar\Sextant\Contracts\SextantActionContract::class