glebkaf/query-filter-bundle
A Symfony bundle for adding reusable, declarative query filters to Doctrine. Define filter criteria once and apply them across requests, replacing hand-written conditional query logic with a consistent, configurable filtering layer that keeps controllers and repositories clean.
First, calibrate expectations: artprima/query-filter-bundle is a Symfony bundle, not a Laravel package. It ships a Bundle subclass wired through Symfony's kernel, Resources/config service definitions, and (typically) Doctrine ORM integration. There is no Illuminate\Support\ServiceProvider and no package auto-discovery, so composer require alone will not make anything usable in a Laravel app. Treat any adoption as "port the underlying filtering logic" or "run it in a legacy Symfony service that a Laravel app talks to," not "install and go."
What changed in fix-deps matters for step one, because it changes how you install it:
sensio/extra-bundle is dropped — good news, that bundle is abandoned and drags in a stale Symfony constraint tree. If you were previously pinning an old Symfony version just to satisfy it, that pin can now go.https://github.com/glebkaf/query-filter-bundle plus the constraint "artprima/query-filter-bundle": "fix-deps".So the minimal install is:
{
"repositories": [
{ "type": "vcs", "url": "https://github.com/glebkaf/query-filter-bundle" }
],
"require": {
"artprima/query-filter-bundle": "fix-deps"
},
"minimum-stability": "dev",
"prefer-stable": true
}
Run composer update artprima/query-filter-bundle --prefer-source and confirm the resolved reference is the commit you expect (composer show artprima/query-filter-bundle). Then look first at the bundle's DependencyInjection/ directory: that is where the service IDs, aliases, and configuration keys live, and it is the only reliable map of the public surface. Ignore the Resources/config/*.xml|yaml files until you know which service you actually need.
The first real use case: you have a Laravel-facing API and an existing Symfony/Doctrine subsystem (or a port of one) that needs to accept arbitrary filter criteria from a query string — ?filter[name]=foo&filter[createdAt][gte]=2024-01-01 — and translate them into a constrained query. Reach for the bundle's filter service, not the bundle's HTTP layer, because the HTTP layer assumes Symfony\Component\HttpFoundation\Request and you will be handing it a Illuminate\Http\Request.
Wrap, don't register. Since the bundle's extension is Symfony-kernel-shaped, the practical pattern in Laravel is a thin adapter registered in AppServiceProvider:
$this->app->singleton(QueryFilter::class, function ($app) {
// construct the filter object directly; skip the bundle's container wiring
return new QueryFilter(/* allowed fields, aliases, defaults */);
});
You get Laravel's container semantics and testability without pretending the bundle's compiler passes exist.
Bridge the request explicitly. A small RequestFactory that converts Illuminate\Http\Request::query() into whatever array/parameter bag the filter expects keeps the Symfony types out of your controllers:
final class FilterInput
{
public static function fromRequest(Request $request): array
{
$query = $request->query('filter', []);
return is_array($query) ? $query : [];
}
}
Validate and whitelist at this boundary. Never pass raw query input into the filter's field resolution.
Map to Eloquent, not Doctrine. The filter produces criteria; the query builder is yours. Apply criteria in a dedicated QueryBuilder/Scope class so the filter stays a pure input-to-criteria translator. This also means you can unit test the criteria without a database.
Treat allowlisting as configuration, not code. Put the permitted fields, their aliases, and their operators in config/query-filter.php and cache it. Any pattern where the query string can name an arbitrary column is a data-exfiltration bug waiting to happen.
Testing pattern. Assert on the produced criteria array, not on generated SQL. SQL assertions break on every driver or Laravel version bump. One integration test per operator family (eq, gte, like, in) plus a rejection test for a non-allowlisted field is usually enough coverage.
"fix-deps" is a branch name used as a version constraint. It is not semver, it will not satisfy ^1.0 style constraints, and it will float. Composer records the resolved commit in composer.lock, so lock the file in and pin to the commit hash ("dev-fix-deps#abc1234") if you want reproducibility across composer update. For anything production-facing, pin.composer update hits the git host on every resolution; CI without git access or with rate limits will fail. Mirror the fork internally if you depend on it long-term.sensio/extra-bundle is a breaking change in the other direction: if your app still registers SensioExtraBundle for other reasons, that's now your direct dependency, not the bundle's. Nothing will break, but you may find the constraint relaxed enough that a composer update pulls a Symfony major you didn't plan for. Pin your Symfony components explicitly and re-run the test suite after upgrading.extra.laravel block, no service provider. If you added it expecting zero-config, you'll get a confusing "class not found" or, worse, silent no-op.composer why sensio/extra-bundle right after install tells you whether the dependency is truly gone from the tree or merely relaxed. composer show -t artprima/query-filter-bundle shows the transitive graph — check the Symfony version range it now allows.Request vs Laravel Request is the single most common failure mode when wiring this into Laravel: type errors that look like namespace problems. Keep the conversion in one place (the FilterInput class above) so there's exactly one spot to fix.How can I help you explore Laravel packages today?