pointybeard / laravel-filterable-model
Add filtering via http request query params to eloquent models
Installs: 2 031
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 2
Forks: 0
Open Issues: 0
Type:project
Requires
- php: >=8.1.0
- illuminate/database: ^9.17 || ^10.23
- illuminate/http: ^9.17 || ^10.23
- illuminate/support: ^9.17 || ^10.23
- spatie/laravel-data: ^3.9
- webmozart/assert: ^1.11
Requires (Dev)
- ext-pcov: *
- ergebnis/composer-normalize: ^2.35
- laravel/framework: ^9.0 || ^10.0
- laravel/pint: ^1.0
- nunomaduro/larastan: ^2.6
- orchestra/testbench: ^7.5 || ^8.10
- php-parallel-lint/php-console-highlighter: ^1.0
- php-parallel-lint/php-parallel-lint: ^1.3
- phpstan/extension-installer: ^1.3
- phpstan/phpstan-deprecation-rules: ^1.1
- phpstan/phpstan-phpunit: ^1.3
- phpstan/phpstan-strict-rules: ^1.2
- phpstan/phpstan-webmozart-assert: ^1.2
- thecodingmachine/phpstan-safe-rule: ^1.2
README
Add filtering via http request query params to Eloquent models in Laravel
Installation
> composer require pointybeard/laravel-filterable-model
Usage
Extend your Eloquent models with Pointybeard\FilterableModel\AbstractFilterableModel
and then use the trait Pointybeard\FilterableModel\Traits\FilterableTrait
. This will add a new scope called filter
, as well as the following methods, to your model:
getFilterable()
getSortable()
getSortByDefault()
getSortOrderDefault()
Then, add protected properties $filterable
, $sortable
, $sortByDefault
, and $sortOrderDefault
to control the behaviour of filtering. E.g.
protected $filterable = ['title', 'category', 'tags', 'is_published']; protected bool $sortable = true; protected string $sortByDefault = 'published_at'; // default is 'created_at' protected string $sortOrderDefault = 'desc'; // default is 'asc'
Finally, you can use the ->filter()
scope to filter results by passing an instance of Filter
. E.g.
use App\Models\MyModel; use Pointybeard\FilterableModel\Filter; MyModel::filter(new Filter( filters: [ 'tag' => 'article', 'is_published' => 1, ], ));
Alternatively, use the Filter::fromRequest()
method to build a filter from request query params, e.g. in your controllers like so:
use App\Models\MyModel; use Pointybeard\FilterableModel\Filter; return response()->json( MyModel::filter(Filter::fromRequest($request))->get(), Response::HTTP_OK );
By default, all comparisons are done by injecting an equals (=
) where clause into the database calls. To use other comparisons, or add more complex logic, create a new class that extends Pointybeard\FilterableModel\Filter
and add your own methods. For example, to use a LIKE
comparison for your tag
field and a boolean comparison for is_published
:
use Pointybeard\FilterableModel\AbstractFilterableModel; use Pointybeard\FilterableModel\Filter; use Illuminate\Database\Eloquent\Builder; Class MyModelFilter extends Filter { public function tag(Builder $builder, AbstractFilterableModel $model, string $value): Builder { return $builder->where('tag', 'like', "%{$value}%"); } public function is_published(Builder $builder, AbstractFilterableModel $model, string $value): Builder { // Convert a string representation of true/false into an actual boolean $value = in_array(strtolower($value), ['1', 'true', 'yes']) ? true : false; return $builder->where('protected', $value); } }
Contributing
We encourage you to contribute to this project. Please check out the Contributing documentation for guidelines about how to get involved.
Support
If you believe you have found a bug, please report it using the GitHub issue tracker.
Authors
License
"Laravel Filterable Model" is released under the MIT License. See LICENCE for details.