PHPackages cerbero/query-filters - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Database & ORM](/categories/database) 4. / 5. cerbero/query-filters ActiveLibrary[Database & ORM](/categories/database) cerbero/query-filters ===================== Filter Laravel Eloquent models based on query parameters. 1.8.1(11mo ago)85282.6k—2.2%16MITPHPPHP ^5.6||^7.0||^8.0 Since Apr 25Pushed 11mo ago4 watchersCompare [ Source](https://github.com/cerbero90/query-filters)[ Packagist](https://packagist.org/packages/cerbero/query-filters)[ Docs](https://github.com/cerbero90/query-filters)[ GitHub Sponsors](https://github.com/cerbero90)[ RSS](/packages/cerbero-query-filters/feed)WikiDiscussions develop Synced 1mo ago READMEChangelogDependencies (8)Versions (15)Used By (0) Query Filters ============= [](#query-filters) [![Author](https://camo.githubusercontent.com/fffbc89ca2742dccf8be167716e04b7125a913abae0da6a488131999dab8ca25/68747470733a2f2f696d672e736869656c64732e696f2f7374617469632f76313f6c6162656c3d617574686f72266d6573736167653d6365726265726f393026636f6c6f723d353041424631266c6f676f3d74776974746572267374796c653d666c61742d737175617265)](https://twitter.com/cerbero90)[![PHP Version](https://camo.githubusercontent.com/5943565c67083c43867aeb06463434252b9522e2b95751bb7a0a34edd014cb00/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6365726265726f2f71756572792d66696c746572733f636f6c6f723d253233344635423933266c6f676f3d706870267374796c653d666c61742d737175617265)](https://www.php.net)[![Laravel Version](https://camo.githubusercontent.com/d9bb040c54e0d4310cf6d38605b1317f50dd92d9f55ec0b15596e0f10c7699d6/68747470733a2f2f696d672e736869656c64732e696f2f7374617469632f76313f6c6162656c3d6c61726176656c266d6573736167653d254532253839254135352e3426636f6c6f723d666632643230266c6f676f3d6c61726176656c267374796c653d666c61742d737175617265)](https://laravel.com)[![Octane Compatibility](https://camo.githubusercontent.com/2bab41dd2c082d2a58c113b9fdd1fa5e56faafbfabd83b9195bab7ef1484b9e1/68747470733a2f2f696d672e736869656c64732e696f2f7374617469632f76313f6c6162656c3d6f6374616e65266d6573736167653d636f6d70617469626c6526636f6c6f723d666632643230266c6f676f3d6c61726176656c267374796c653d666c61742d737175617265)](https://github.com/laravel/octane)[![Build Status](https://camo.githubusercontent.com/28be28a989c6efc0405238a256cdb2215a71a2d00fe27de20a9b2d2d335bdb0e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f6365726265726f39302f71756572792d66696c746572732f6275696c643f7374796c653d666c61742d737175617265266c6f676f3d676974687562)](https://github.com/cerbero90/query-filters/actions?query=workflow%3Abuild)[![Coverage Status](https://camo.githubusercontent.com/832b34f1ba0979fec747f21ea6a5e5785e013c71899cc2173da8f705e2ecdf3e/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f636f7665726167652f672f6365726265726f39302f71756572792d66696c746572732e7376673f7374796c653d666c61742d737175617265266c6f676f3d7363727574696e697a6572)](https://scrutinizer-ci.com/g/cerbero90/query-filters/code-structure)[![Quality Score](https://camo.githubusercontent.com/984058aab5aa1beb91af9cc145fcf1d1c64d0cb966ae3f12adf676f63e4aee8d/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f6365726265726f39302f71756572792d66696c746572732e7376673f7374796c653d666c61742d737175617265266c6f676f3d7363727574696e697a6572)](https://scrutinizer-ci.com/g/cerbero90/query-filters)[![Latest Version](https://camo.githubusercontent.com/c4cfd5d9e477f861a1bfd3ffc83ce13783557322992c5530c0b9615237951634/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6365726265726f2f71756572792d66696c746572732e7376673f6c6162656c3d76657273696f6e267374796c653d666c61742d737175617265)](https://packagist.org/packages/cerbero/query-filters)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)[![PSR-12](https://camo.githubusercontent.com/9ba5754b3504e97a10e2b2f84770a218e69e544e9de8943eceb0b67599c83c6c/68747470733a2f2f696d672e736869656c64732e696f2f7374617469632f76313f6c6162656c3d636f6d706c69616e6365266d6573736167653d5053522d313226636f6c6f723d626c7565267374796c653d666c61742d737175617265)](https://www.php-fig.org/psr/psr-12/)[![Total Downloads](https://camo.githubusercontent.com/7961fcf49a8c8b43787b7014549fd1e6565d0bde4763a9470ed1456c5cda03fe/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6365726265726f2f71756572792d66696c746572732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cerbero/query-filters) [![SensioLabsInsight](https://camo.githubusercontent.com/27d7adfd41a2b52aef7434422952ed15131d328f607e2b3a7923e332de3f872a/68747470733a2f2f696e73696768742e73656e73696f6c6162732e636f6d2f70726f6a656374732f66653563623830622d643439662d343665362d623934622d3739633630383762356331332f6269672e706e67)](https://insight.sensiolabs.com/projects/fe5cb80b-d49f-46e6-b94b-79c6087b5c13) Query Filters was fully inspired by [this lesson on Laracasts](https://laracasts.com/series/eloquent-techniques/episodes/4), it provides a simple way to filter Eloquent models based on query parameters of an HTTP request. Install ------- [](#install) Via Composer: ``` composer require cerbero/query-filters ``` If your version of Laravel is prior to 5.5, you can register this package service provider by adding the following line to the list of providers in `config/app.php`: ``` 'providers' => [ ... Cerbero\QueryFilters\Providers\QueryFiltersServiceProvider::class, ] ``` This package includes a generator for query filter classes that by default are generated in `app/QueryFilters`. If you prefer a different path, you can set it in the `config/query_filters.php` file after running: ``` php artisan vendor:publish --tag=query_filters_config ``` Usage ----- [](#usage) Imagine to have a route for indexing all actors stored in the database. This route accepts query parameters to filter records, for example: ``` /actors?won_oscar&acting=0&acted-in=2000 ``` In this case the route will need to display only actors who won at least one Oscar, are no longer acting but acted in 2000. This can be achieved by generating a query filters class and optionally defining the allowed query parameters and related variable names via the following Artisan command: ``` php artisan make:query-filters ActorFilters 'won_oscar&acting=bool&acted-in=year' ``` That command will generate and populate with filters the `ActorFilters` class: ``` use Cerbero\QueryFilters\QueryFilters; /** * Filter records based on query parameters. * */ class ActorFilters extends QueryFilters { /** * Filter records based on the query parameter "won_oscar" * * @return void */ public function wonOscar() { // $this->query } /** * Filter records based on the query parameter "acting" * * @param mixed $bool * @return void */ public function acting($bool) { // $this->query } /** * Filter records based on the query parameter "acted-in" * * @param mixed $year * @return void */ public function actedIn($year) { // $this->query } } ``` Please note how filter names are the equivalent camel case form of their related query parameters. Filters are only applied if their query parameter is present in the HTTP request with a non-empty value, unless they need no value to function (e.g. `won_oscar`). The `$query` property lets filters determine how queries change when they are applied: ``` public function wonOscar() { $this->query->where('oscars', '>', 0); } public function acting($bool) { $this->query->where('acting', $bool); } public function actedIn($year) { $this->query->whereHas('movies', function ($movies) use ($year) { $movies->whereYear('release_date', '=', $year); }); } ``` After filters are defined, Eloquent models can apply them by using the `FiltersRecords` trait: ``` use Cerbero\QueryFilters\FiltersRecords; use Illuminate\Database\Eloquent\Model; class Actor extends Model { use FiltersRecords; } ``` Finally in your route you can filter actors by calling the method `filterBy()` of your model and passing the query filters: ``` use App\Actor; use App\QueryFilters\ActorFilters; ... public function index(ActorFilters $filters) { return Actor::filterBy($filters)->get(); } ``` Alternatively you can hydrate query filters from a plain array: ``` 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(); } ``` Sometimes you may want to silently skip filters if their value is not valid. Instead of setting validation rules in HTTP requests, you may define them in the query filters class. This avoids a failed validation to stop the filtering process and applies only valid filters while ignoring filters with values that do not pass the validation: ``` class ActorFilters extends QueryFilters { protected function getRules() { return [ 'acting' => 'bool', 'acted-in' => 'int|digits:4', ]; } } ``` Change log ---------- [](#change-log) Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently. Testing ------- [](#testing) ``` composer test ``` Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) and [CONDUCT](CONDUCT.md) for details. Security -------- [](#security) If you discover any security related issues, please email instead of using the issue tracker. Credits ------- [](#credits) - [Jeffrey Way](https://github.com/JeffreyWay) - [Laracasts](https://laracasts.com) - [Andrea Marco Sartori](https://twitter.com/cerbero90) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 52 — FairBetter than 96% of packages Maintenance50 Moderate activity, may be stable Popularity49 Moderate usage in the ecosystem Community15 Small or concentrated contributor base Maturity76 Established project with proven stability Bus Factor1 Top contributor holds 98.5% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~277 days Recently: every ~446 days Total 13 Last Release 349d ago PHP version history (4 changes)1.0.0PHP ~5.5|~7.0 1.2.1PHP ~5.6|~7.0 1.4.0PHP ^5.6|^7.0 1.7.0PHP ^5.6||^7.0||^8.0 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/596523?v=4)[Matteo Picciolini](/maintainers/cerbero)[@cerbero](https://github.com/cerbero) --- Top Contributors [![cerbero90](https://avatars.githubusercontent.com/u/5838106?v=4)](https://github.com/cerbero90 "cerbero90 (64 commits)")[![chapus](https://avatars.githubusercontent.com/u/1543053?v=4)](https://github.com/chapus "chapus (1 commits)") --- Tags laraveleloquentqueryfilterscerberoquery-filters ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/cerbero-query-filters/health.svg) ``` [![Health](https://phpackages.com/badges/cerbero-query-filters/health.svg)](https://phpackages.com/packages/cerbero-query-filters) ``` ### Alternatives [tucker-eric/eloquentfilter An Eloquent way to filter Eloquent Models 1.8k4.8M26](/packages/tucker-eric-eloquentfilter)[reedware/laravel-relation-joins Adds the ability to join on a relationship by name. 2121.2M13](/packages/reedware-laravel-relation-joins)[mehdi-fathi/eloquent-filter Eloquent Filter adds custom filters automatically to your Eloquent Models in Laravel.It's easy to use and fully dynamic, just with sending the Query Strings to it. 450191.6k1](/packages/mehdi-fathi-eloquent-filter)[jerome/filterable Streamline dynamic Eloquent query filtering with seamless API request integration and advanced caching strategies. 19226.1k](/packages/jerome-filterable)[aldemeery/sieve A simple, clean and elegant way to filter Eloquent models. 1396.3k](/packages/aldemeery-sieve)[baril/bonsai An implementation of the Closure Tables pattern for Eloquent. 3593.5k](/packages/baril-bonsai) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)