Download the PHP package plokko/resource-query without Composer

Resource-query

Automatic filtering and sorting for Laravel queries with Ajax capabilities.

Scope of this package

This package adds classes that help automate the creation of back-end defined user queries (Ajax) with advanced functions like filtering, sorting, pagination, resource casting and smart casting. The query will be based on a pre-defined Eloqent query and the user may customize the query by applying pre-defined query parameters. All the query parameters are easly defined and customized in the back-end allowing strict control on what the user can see or do.

Installation

Install it via composer composer require plokko/resource-query

Initialization

To use this class you must extend the base ResourceQuery class or use a builder. Exending ResourceQuery class is preferred if you plan to reutilize the same settings, the builder approach is quicker if you plan to use it one time only.

Extending ResourceQuery

Create a new class that extends plokko\ResourceQuery\ResourceQuery and implement the function getQuery() that will return the base query

Using the builder

Or by defining it in-place with ResourceQueryBuilder

Example usage

Adding filters

Filters are composed of a filter name (request query parameter associated with the filter), a condition used to parse the filters and a (optional) field name used to specify the table field to apply the filter to.

The condition can be either a base query condition (like =,!=,<>,like,in, etc.), a shortand helper like like%,%like or %like% that will add a "%" character before, after or at both ends of the input or a Callable function that will resolve the filter. To the Callable filter will be passed 3 parameters:

0. \Illuminate\Database\Query\Builder|\Illuminate\Database\Eloquent\Builder query - The query where to apply the filter
1. mixed $value - The filtered value
2. FilterCondition $condition - The current condition, used to retrive condition or field name, etc.

You can add the filter in many ways:

You can also define or modifiy filter conditions or field name with the condition or field functions, ex:

You can remove a filter with

or with unset function

If you wish to remove all filters use

Filter definition

Filters can be added either during class inizialization (if extended ResourceQuery)

Or by directly calling the resource

Filter root name

If you want to encapsulate all your filter in an array (ex. "url?filter[filter-name]=value" ) you can define it with setFiltersRoot

or by setting $filtersRoot in the class definition:

Additional filter rules

Default filter value

If you want to apply a default value if the field is not present you can use defaultValue function:

Value formatting

If you want to format the filter value (ex. escaping characters, capitalize, etc.) before the filter is applied you can add a callable function with the formatValue function. The original filter value will be passed as a parameter and the return value will be used as the new filter value.

Example:

Apply only if another filter is present

If you want to apply a filter ONLY if one or more filters are present you can use applyIfPresent function

Apply only if another filter is absent

If you want to apply a filter ONLY if one or more filters are absent you can use applyIfNotPresent function

Sorting

Like with filtering you can declare sorting query parameters via the OrderBy parameter in many ways:

For each filter you can specify a related table field to order with the field('<FIELD>') function and a default sorting direction with defaultOrder('<DIRECTION>'). If you want the sorting direction to be fixed and not modifiable by the user you can use the direction('<DIRECTION>') method.

If you want to customize the sorting you can pass a callback as the field parameter; the query where the sorting will be applied will be passed as first argument and the sorting direction as second argument.

Example:

Default sorting order

If you want to specify a default sorting order you can

Order query parameter

The filter query parameter can be set with the $orderField parameter of the ResourceQuery. The filter can be specified as a key value with the sorting parameter as key and the direction as a value or by using one of the two short syntax (as string, comma separated):

• <sorting_parameter>[:<direction>]
• [+|-]<sorting_parameter> where prepending "+" means ascending order and "-" descending order

Example:

page?order_by[field1]=&order_by[field2]=asc&order_by[field3]=desc

Or

page?order_by=field1,field2:asc,field3:desc

Or

page?order_by=field1,+field2,-field3

Javascript API

The package does include a Javascript counterpart to help query the back-end; the package is distributed with the composer package instead of a separate npm package as it's strictly related to the php implementation.

Include it in resources/js/app.js

Note: Axios is required as a dependency

Usage

Instantiate a new ResourceQuery by specifying target URL and method (default get):

The back-end should be something as follow:

You can add or modify filters, sorting and options

Request cancellation and options

Request cancellation is supported via a token option:

See Axios request configuration for other supported configuration options (some proprieties may be ignored)