Laravel package to filter data based on the query string. Fully inspired by Laracasts (https://laracasts.com/series/eloquent-techniques/episodes/4)
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src Also check if a value is null because of the ConvertEmptyStringsToNul… Aug 16, 2017
tests Also check if a value is null because of the ConvertEmptyStringsToNul… Aug 16, 2017
.editorconfig Import files from Skeleton Apr 25, 2016
.gitattributes
.gitignore Import files from Skeleton Apr 25, 2016
.scrutinizer.yml Import files from Skeleton Apr 25, 2016
.styleci.yml Import files from Skeleton Apr 25, 2016
.travis.yml Remove support for PHP 5.5 Nov 19, 2016
CHANGELOG.md Update CHANGELOG.md Aug 16, 2017
CONDUCT.md Import files from Skeleton Apr 25, 2016
CONTRIBUTING.md Import files from Skeleton Apr 25, 2016
LICENSE.md
README.md Fix missing $ symbol in property Aug 16, 2017
composer.json Remove support for PHP 5.5 Nov 19, 2016
phpspec.yml Import files from Skeleton Apr 25, 2016

README.md

Query Filters

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

SensioLabsInsight

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

License

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