PHPackages goodcat/laravel-filter-querystring - 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. goodcat/laravel-filter-querystring ActiveLibrary[Database & ORM](/categories/database) goodcat/laravel-filter-querystring ================================== A laravel package to filter Eloquent models using query string parameters v2.1.0(1mo ago)220MITPHPPHP ^8.2CI passing Since Feb 7Pushed 9mo ago1 watchersCompare [ Source](https://github.com/goodcat-dev/laravel-filter-querystring)[ Packagist](https://packagist.org/packages/goodcat/laravel-filter-querystring)[ Docs](https://github.com/goodcat-dev/laravel-filter-querystring)[ RSS](/packages/goodcat-laravel-filter-querystring/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (18)Versions (9)Used By (0) Laravel Filter Query String =========================== [](#laravel-filter-query-string) [![Latest Version on Packagist](https://camo.githubusercontent.com/a888161958c071e506708e8bcf93d15924ebd547f4bd525c7737eeb913d7f212/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f676f6f646361742f6c61726176656c2d66696c7465722d7175657279737472696e672e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/goodcat/laravel-filter-querystring)[![GitHub Tests Action Status](https://camo.githubusercontent.com/0cc28bc467103c523258c8b99285a410af25e04967dac2bc48265cfc05cc8845/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f676f6f646361742d6465762f6c61726176656c2d66696c7465722d7175657279737472696e672f74657374732e79616d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/goodcat-dev/laravel-filter-querystring/actions?query=workflow%3Atests+branch%3Amain) This package allows you to filter Eloquent models using query string parameters. Quick Start ----------- [](#quick-start) Get started with `laravel-filter-querystring` in three steps. 1. Download the package via Composer. ``` composer require goodcat/laravel-filter-querystring ``` 2. Add the `UseQueryString` trait to your model and tag a method with the `QueryString` attribute. ``` use Illuminate\Database\Eloquent\Builder; use Goodcat\QueryString\Traits\UseQueryString; use Goodcat\QueryString\Attributes\QueryString; class User extends Authenticatable { use UseQueryString; #[QueryString('email')] public function filterByEmail(Builder $query, string $search): void { $query->where('email', $search); } } ``` 3. Use the `queryString()` scope when you want to filter models based on query string parameters in the request. ``` class UserController extends Controller { public function index(Request $request): View { // E.g. https://example.com/users?email=john@doe.com $users = User::query()->queryString($request)->get(); return view('user.index', ['users' => $users]); } } ``` That's it. You're all set to start using `laravel-filter-querystring`. Caching ------- [](#caching) `laravel-filter-querystring` scans your code to locate methods tagged with the `QueryString` attribute. While the performance impact of this discovery is negligible, you can cache these methods using the Artisan command `querystring:cache`. To clear the cache, use the Artisan command `querystring:clear`. ``` php artisan querystring:cache ``` To streamline your deployment process, `laravel-filter-querystring` integrates with Laravel's `optimize` command. Use the `optimize` and `optimize:clear` commands to create and remove the cache. Configuration ------------- [](#configuration) To publish the config file to `config/querystring.php` run the command: ``` php artisan vendor:publish --provider="Goodcat\QueryString\QueryStringServiceProvider" ``` ### Handling `null` values [](#handling-null-values) The `null` values are ignored by `laravel-filter-querystring`. If you want `null` values passed to your function, set `'allows_null'` to `true` in `config/querystring.php` file. Digging deeper -------------- [](#digging-deeper) Let's take a closer look at how `laravel-filter-querystring` works under the hood and explore its advanced features. ### `#[QueryString]` attribute [](#querystring-attribute) The `QueryString` attribute is used to map the *name of a query string* to a method. The attribute name must match the query string name. ``` #[QueryString('name')] public function filterByName(Builder $query, string $search): void ``` E.g. The string `name` in the URL `http://example.com/?name=John+Doe` is mapped to the method tagged with the `#[QueryString('name')]` attribute. ### Filter methods [](#filter-methods) The filter method receives three parameters: the query builder, the query string value and the query string name. You can add multiple attributes to the same method. ``` #[QueryString('name')] #[QueryString('email')] public function genericStringSearch(Build $query, string $search, string $name): void { $query->where($name, 'like', "$search%"); } ``` ### `queryString()` scope [](#querystring-scope) The `queryString()` scope is responsible for calling your filter methods. It accepts a `Request` or an `array`. ``` public function index(Request $request): View { $filters = $request->query(); // Change $filters array as desired. $users = User::query()->queryString($filters)->get(); return view('user.index', ['users' => $users]); } ``` Laravel uses `TrimStrings` and `ConvertEmptyStringsToNull` middlewares to trim and nullify empty strings from requests. If you pass an `array` to the filter method, it's up to you to normalize the passed value. ### Filter object [](#filter-object) By default, `laravel-filter-querystring` searches the model for filter methods. If you wish, you can register a different class by overriding the `getQueryStringObject()` method. ``` class User extends Authenticatable { use UseQueryString; protected function getQueryStringObject(): object { return new CustomFilterClass(); } } ``` ### Health Score 39 — LowBetter than 86% of packages Maintenance72 Regular maintenance activity Popularity9 Limited adoption so far Community9 Small or concentrated contributor base Maturity56 Maturing project, gaining track record Bus Factor1 Top contributor holds 65.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 ~59 days Recently: every ~71 days Total 8 Last Release 46d ago Major Versions v0.1.1 → v1.0.02025-02-14 v1.1.1 → v2.0.02026-03-22 ### Community Maintainers ![](https://www.gravatar.com/avatar/6ca068e1dd24801f83c4c4802af654bdb2db4025499aa94d0575898a4a5d5c8f?d=identicon)[OutlawPlz](/maintainers/OutlawPlz) --- Top Contributors [![OutlawPlz](https://avatars.githubusercontent.com/u/14197383?v=4)](https://github.com/OutlawPlz "OutlawPlz (36 commits)")[![matteo-palazzo](https://avatars.githubusercontent.com/u/83695398?v=4)](https://github.com/matteo-palazzo "matteo-palazzo (19 commits)") --- Tags query-stringlaravelmodeleloquentfiltersgoodcat ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/goodcat-laravel-filter-querystring/health.svg) ``` [![Health](https://phpackages.com/badges/goodcat-laravel-filter-querystring/health.svg)](https://phpackages.com/packages/goodcat-laravel-filter-querystring) ``` ### Alternatives [tucker-eric/eloquentfilter An Eloquent way to filter Eloquent Models 1.8k4.8M26](/packages/tucker-eric-eloquentfilter)[toponepercent/baum Baum is an implementation of the Nested Set pattern for Eloquent models. 3154.7k](/packages/toponepercent-baum)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 245.2k](/packages/aedart-athenaeum) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)