tiagomichaelsousa/laravelfilters
Laravel Filters lets you filter Eloquent models directly from query strings. Define reusable filter classes, attach them to models with a simple trait, and compose filters per request. Includes artisan generators for creating filters quickly, keeping controllers clean and queries readable.
Install with composer require tiagomichaelsousa/laravel-filters:^1.7 and confirm your app meets the package’s PHP/Laravel constraints. v1.7.0 is primarily a compatibility release: it adds Laravel 11 support and Laravel 12.x compatibility, with no documented breaking API changes in the release notes.
Look first at the package README, then the filter class examples and changelog. In a Laravel 11/12 app, confirm package auto-discovery is working and check whether any config is publishable before adding custom configuration. Clear cached config after upgrading:
php artisan optimize:clear
The first practical use case is an index endpoint with optional query-string filters, for example GET /users?status=active&search=ana. Create a dedicated filter class for the model, map only approved query keys to Eloquent constraints, then apply the filter from the controller and paginate the result. Keep the filter class close to the model/domain it serves, such as app/Filters/UserFilter.php.
Use one filter class per model or read model. This keeps query-string handling out of controllers and makes filters reusable across web, API, and admin endpoints.
Treat filters as an explicit allowlist. Each public filter method should represent a supported query parameter, and controllers/form requests should validate and normalize incoming values before the filter runs.
A typical workflow:
status, search, created_after, or role.For complex filters, keep the method focused and compose Eloquent constraints inside it. Use whereHas for relationship filters, explicit date parsing for date ranges, and when() or early returns for optional values. Avoid letting raw request arrays reach whereRaw, orderBy, or column-name interpolation.
Filters compose well with authorization and response layers: authorize the request first, apply filters second, then return API resources or paginated collections. If filters are used in multiple endpoints, extract shared filter behavior into a base filter class or model-specific trait rather than duplicating query logic.
For tenant-aware or role-aware applications, apply tenant scoping through global scopes or a base filter, not through user-supplied query parameters. Keep filter behavior deterministic and test it against the same database engine used in production.
v1.7.0 is a compatibility release, not a feature release. Upgrading from v1.6.0 should be low-risk, but run the full test suite and verify composer constraints, service-provider discovery, and cached config in Laravel 11/12. If an older Laravel version is pinned, Composer may keep you on v1.6.0; check the resolved version with composer show.
Do not expose every public method as a filter. If the package maps query keys to filter methods, unintended public methods can become callable filters. Keep filter methods intentional, validate keys, and reject unknown parameters where appropriate.
Watch for empty-string, boolean, array, and null query values. Normalize them in a form request or filter base class before building queries. Preserve filters across pagination links with withQueryString().
Be careful with LIKE filters. Escape or constrain wildcard input where needed, and never interpolate user input into raw SQL fragments or column names. Validate sortable columns separately if you add sorting alongside filtering.
When debugging, inspect the generated SQL and bindings after applying the filter:
$query = User::filter(/* ... */);
dump($query->toSql(), $query->getBindings());
Also log or dump which filter class and filter keys were applied. This quickly reveals namespace mismatches, method-name typos, visibility problems, or values that were silently ignored.
Extension points to use deliberately: a custom base filter class, overridden filter application logic, custom request-to-filter mapping, global filters for tenancy, and model-specific filter classes. Keep these extensions tested, because they are the parts most likely to be affected by future Laravel compatibility releases.
How can I help you explore Laravel packages today?