Laravel package to filter data based on the query string.

1.3.1 2017-08-16 13:21 UTC


Author Latest Version on Packagist Software License Build Status Coverage Status Quality Score StyleCI Total Downloads Gratipay


Query Filters has been fully inspired by this lesson on Laracasts. This package provides an elegant and dynamic way to filter database records based on the request query string.


From the root of your project run the following command in the terminal:

composer require cerbero/query-filters

Optionally you can register the service provider included in the package to create query filters via the Artisan command make:query-filters FiltersName. In order to do that, add the following line to the list of your providers in config/app.php:

'providers' => [

By default the newly created query filters are placed in app/QueryFilters, if you prefer a different path you can set it in the config/query_filters.php file that you can create by running:

php artisan vendor:publish --tag=query_filters_config


Imagine having a route to index all the actors stored in our database. This route accepts a query string to filter the data to display. For instance:


will display only actors who won at least one Oscar, are no longer acting but acted in 2000.

By using this package you can easily create filters based on the requested query string by just extending the QueryFilters class:

use Cerbero\QueryFilters\QueryFilters;

class ActorFilters extends QueryFilters
    protected $implicitFilters = [

    public function wonOscar()
        $this->query->where('oscars', '>', 0);

    public function acting($boolean)

    public function actedIn($year)
        $this->query->whereHas('movies', function ($movies) use ($year) {
            $movies->whereYear('release_date', '=', $year);

All parameters in the query string have the related method in the newly created class. Please note that parameters having dashes or underscores are converted into their respective camel case form.

By default filters are not applied whether their value is an empty string. If you wish to have implicit filters (e.g. wonOscar()) you can list them in the property $implicitFilters and they will be applied just like the others when the related query parameter is present in the request.

You can use the property $query to interact with the Laravel Query Builder and determine how filters work. Thereafter let your Eloquent model (e.g. Actor) use the FiltersRecords trait:

use Cerbero\QueryFilters\FiltersRecords;
use Illuminate\Database\Eloquent\Model;

class Actor extends Model
    use FiltersRecords;

Now you can filter your actors by calling the method filterBy() and passing an instance of ActorFilters. For example, in your controller:

use App\Actor;
use App\QueryFilters\ActorFilters;


public function index(ActorFilters $filters)
    return Actor::filterBy($filters)->get();

Alternatively you can hydrate an instance of QueryFilters from an array of query parameters, like:

use App\Actor;
use App\QueryFilters\ActorFilters;
use Illuminate\Http\Request;


public function index(Request $request)
    $filters = ActorFilters::hydrate($request->query());

    return Actor::filterBy($filters)->get();

Change log

Please see CHANGELOG for more information what has changed recently.


composer test


Please see CONTRIBUTING and CONDUCT for details.


If you discover any security related issues, please email andrea.marco.sartori@gmail.com instead of using the issue tracker.



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