Query Filters

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.

Install

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' => [
    ...
    Cerbero\QueryFilters\QueryFiltersServiceProvider::class,
    ...
]

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

Usage

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:

/actors?won_oscar&acting=0&acted-in=2000

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 = [
        'wonOscar',
    ];

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

    public function acting($boolean)
    {
        $this->query->whereActing($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.

Testing

composer test

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

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

Credits

• Jeffrey Way
• Laracasts
• Andrea Marco Sartori
• All Contributors

License

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