Download the PHP package dorvidas/laravel-query-builder without Composer

Easily build Eloquent queries from API requests

This package allows you to filter and include eloquent relations based on a request. Filtering is possible even on relations. Query parameter names follow the JSON API specification as closely as possible.

Basic usage

Filtering an API request by checking if column equals to value: /users?filter[eq:active]=1 or /users?filter[active]=1(if no filter defined, the default eq filter is used):

Requesting filtered relations from an API request: /users?filter[posts.eq:published]=1&include=posts:

Requesting deep relations filtered from an API request: /users?filter[posts.comments.eq:approved=1&include=posts.comments:

Works together nicely with existing queries, because buildFromRequest is basically Eloquent macro: /users?filter[eq:name]=John:

Installation

You can install the package via composer:

You can optionally publish the config file with:

Usage

Filters

Out-of-box filters

There are number of out-of-box filters that can be used right away. Filters are listed in config:

Using filters in URL

JSON:API is agnostic to filtering strategy. The only requirement that filter would be placed in &filter query param. Proposed filter format:

• &filter[eq:id]=1 - Column id equals 1. The part after semicolon is called filter attributes. Can have multiple if filter requires &filter[between:from,to]=2018,2019.
• &filter[posts.eq:id]=1 - define filter for relation posts. If relation is deep we define full path to it posts.comments.eq:id=1.

Create filters

If you need to create custom filter append the config.

Filter should implement Dorvidas\QueryBuilder\FiltersFilterInterface interface. Example filter:

GOTCHAs

Filters with no values are not applied i.e $filter[eq:id]=. Laravel application converts empty query params to null values by using \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class middleware and to filter rows where columns is null use n:your_col=1 filter. Reason for that is when using documentation tools like Swagger I list all possible filters for endpoint and when value is not present I want to skip it.

Including relations

JSON:API allows request for related resources. This is done via include query param i.e. /users?include=posts:

Include constraints

It is possible to add constraints on which includes are allowed. Without it you can request for everything as long as there are requested relation defined i.e. /users?include=posts:

Manually building query

It is also possible to build query manually by using buildFromArray macro and passing instance of \Dorvidas\QueryBuilder\ArrayBuilder to it:

Sparse fields - TODO

Sorting - TODO

Paginating - TODO

Limit results - TODO

Testing

License

The MIT License (MIT). Please see License File for more information.