mnabialek / laravel-eloquent-filter
Allows filtering Eloquent queries by input filters
Installs: 13 247
Dependents: 0
Suggesters: 0
Security: 0
Stars: 25
Watchers: 3
Forks: 11
Open Issues: 7
Requires
- laravel/framework: 5.*|6.*|7.*|8.*
Requires (Dev)
- friendsofphp/php-cs-fixer: ^2.5
- mockery/mockery: ^1.0
- php-coveralls/php-coveralls: ^2.0
- phpunit/phpunit: ^5.4
- dev-master
- v0.1.3
- v0.1.2
- v0.1.1
- v0.1
- dev-dependabot/composer/symfony/http-kernel-5.4.20
- dev-dependabot/composer/guzzlehttp/guzzle-7.4.5
- dev-dependabot/composer/guzzlehttp/psr7-1.8.5
- dev-dependabot/composer/league/flysystem-1.1.4
- dev-dependabot/composer/laravel/framework-8.40.0
- dev-changes
- dev-analysis-X0nVgM
- dev-develop
This package is auto-updated.
Last update: 2024-11-30 02:10:44 UTC
README
This module lets you filter Eloquent data using query filters. You can apply WHERE filters and also set order of results
Installation
-
Run
composer require mnabialek/laravel-eloquent-filter
in console to install this module
-
That's it! Installation is complete. You don't need to adjust any config or install service providers.
Getting started
Let's assume you want to allow to filter users data. By default you use User
Eloquent model to get users. To enable filtering, open User model (by default app/User.php
file) and add into it the following trait:
use \Mnabialek\LaravelEloquentFilter\Traits\Filterable;
just bellow opening class definition, so it should look something like this:
class User extends Authenticatable { use \Mnabialek\LaravelEloquentFilter\Traits\Filterable;
To allow filtering for this class, you need to also create implementation of Mnabialek\LaravelEloquentFilter\Contracts\QueryFilter
interface. To do that create min app/Filters
directory file with the following content:
<?php namespace App\Filters; use Mnabialek\LaravelEloquentFilter\Filters\SimpleQueryFilter; class UserFilter extends SimpleQueryFilter { protected $simpleFilters = ['id','created_at']; protected $simpleSorts = ['id','email','created_at']; }
As you see, you don't implement here the whole contract but you only extend SimpleQueryFilter
class that does it for you.
Now you need to go to place where you get users data. Let's assume in your controller you get your users using:
$users = User::get();
All you need to do now, is changing it into:
$users = User::filtered(\App::make(\App\Filters\UserFilter::class))->get();
Obviously you can use method dependency injection for that instead of using App::make
here but it's only simple example that should work in all places of your app.
Now, let's assume you display your users using http://localhost/users
url.
After those changes running:
http://localhost/users?id=2
- should display user with id = 2 onlyhttp://localhost/users?id[]=2&id[]=5
- should display user with id = 2 and user with id = 5http://localhost/users?sort=created_at,-email
- should display users with created_at ascending and email descending order.
Simple query parser and simple query filter
Although you can create custom parsers and filters, some default ones are provided.
By default you can pass to your url conditions using field with value for example id=5
and you can apply sorting using sort
parameter with names of fields separated by comma. If you precede field by -
sign, it will assume you want to sort by this field in descending order.
When implementing your filter class when you extend SimpleQueryParser
in $simpleFilters
and $simpleSorts
you can specify any fields that might be filtered and sorted without any custom implementation. For those fields simple =
comparison will be used and in case of array usage (for example id[]=2&id[]=5
it will be assumed you want to get data with logical OR
operator.
However in real life you might want to specify custom filter or sort method. To do that, you need to implement your custom method for such field for example:
For created_at
filter you can use
protected function applyCreatedAt($value) { $this->query->whereRaw('DATE(created_at) = ? ', [$value]); }
For id
sort you can use for example:
protected function applySortId($order) { $this->query->orderBy('id',$order)->orderBy('email','asc'); }
You can also implement default filters and default sorting implementing applyDefaultFilters
and applyDefaultSorts
methods where you can check whether any filters or sorts were already applied.
Customization
Although this module provides some default implementations, you can create your own. You can change they way data is passed to QueryFilter. By default SimpleQueryParser
is used that parses Request input in very basic way. However you might want to create your own implementation of Mnabialek\LaravelEloquentFilter\Contracts\InputParser
to fully adjust it to your needs.
You might also change they way filters and sorts are applied to query. To do this, you need to create your own implementation of Mnabialek\LaravelEloquentFilter\Contracts\QueryFilter
but again default implementation was given.
In case you want to only create implementation of QueryFilter, it might be convenient to create custom filter class, that will pass this specific QueryFilter implementation to QueryFilter instead of creating your own constructor in multiple filters classes. You can look at SimpleQueryFilter
which does it for SimpleQueryParser
to remove need of defining this constructor over and over in multiple filter classes (assuming you want to use SimpleQueryParser for them).
Licence
This package is licenced under the MIT license