Extra Filters Bundle Laravel Package

Getting Started

First, confirm the framework fit — this is the whole decision. The -bundle suffix and the InstacarMX origin point to Symfony's bundle conventions: a *Bundle.php class, a DependencyInjection/*Extension.php, and YAML service wiring. Check composer.json for "type": "symfony-bundle" and the autoload.psr-4 namespace (Instacar\ExtraFiltersBundle\). If that holds, there is no Illuminate\Support\ServiceProvider, no config publishing, and no facade — Composer will install it into a Laravel app and then nothing will happen. Decide up front whether you are (a) running it inside a Symfony service, or (b) reading it as a reference implementation to port. Do not attempt a Laravel bridge for a 9-star package with zero dependents.

If you are on Symfony:

1. composer require instacar/extra-filters-bundle — pin the version, don't float. The package is still on 0.x (v0.2.3 is the current tag), so SemVer gives you no compatibility promise at all: require 0.2.3 exactly, not ^0.2.
2. Register it in config/bundles.php (or Kernel::registerBundles() on older skeletons).
3. Read the source in this order: README.md → DependencyInjection/Configuration.php (this file is the public API — it enumerates every config key and default) → the bundle class → the filter classes themselves.

First use case: apply one filter to one query and prove the generated SQL. Wire the minimal config block, run bin/console debug:config <alias> to see the resolved tree, then log the query with Doctrine's SQL logger or the Symfony profiler and confirm the WHERE clause changed. Once one filter is visibly in the SQL, the rest is configuration.

If you are Laravel-only: budget an hour to read Configuration.php and the filter classes, extract the predicate logic, and reimplement as Eloquent local scopes. That is almost always cheaper than maintaining a Symfony/Laravel shim, and it removes the license question entirely (see Gotchas).

Implementation Patterns

Config-first, always. Symfony bundle behavior lives in config/packages/*.yaml and gets merged and validated by the extension. Treat that YAML as production code: commit it, review it, and never configure filters imperatively when a config key exists. After every change, bin/console cache:clear then debug:config — a silently ignored key (typo, wrong nesting level) is the single most common failure mode and produces no error.

Adapter, not direct dependency. Because the package is thinly maintained, do not let filter classes leak into controllers or repositories. Define your own narrow interface:

interface FilterRegistry { public function apply(string $name, $query, array $params): void; }

Implement it once over the bundle, inject the interface everywhere else. When the bundle breaks against a newer Symfony/PHP, you rewrite one class instead of grepping the codebase.

Apply at query-builder level. These filter packages are built for Doctrine QueryBuilder/SQLFilter interception, not post-hydration collection filtering. If you find yourself calling array_filter on results, you have taken the package out of its intended path and lost the index usage.

Port pattern for Laravel. Keep the predicate semantics, drop the DI machinery. Each filter maps cleanly to a local scope:

// Bundle concept: a named filter with typed parameters
// Laravel equivalent:
public function scopeBetweenDates($q, string $col, ?string $from, ?string $to) {
    $q->when($from, fn($q) => $q->where($col, '>=', $from))
      ->when($to,   fn($q) => $q->where($col, '<=', $to));
}

Register the set in a FilterServiceProvider and resolve by name via a small registry array — same shape, zero Symfony surface.

Fork-and-pin if you keep it. Add a repositories entry pointing at your fork, tag it, and require the tag exactly. The v0.2.3 release proved the project is not dead-dead, but commit cadence is measured in years — do not build a dependency on dev-main and do not assume the next compatibility bump arrives before you need it.

Gotchas and Tips

License NOASSERTION is the headline risk. There is no cleanly identifiable license, which means you do not have documented permission to redistribute or embed it. The v0.2.3 release did not change this — a changelog line about Symfony support says nothing about licensing. For internal use this is survivable; for anything shipped, get written clarification from InstacarMX or reimplement the logic. The logic is typically tens of lines — reimplementation is usually the cheaper path, and it makes the port pattern above moot.

Compatibility moved to Symfony 6.2 specifically — read the constraint, not the changelog. v0.2.3 ("Added support for Symfony 6.2") is the first release since 2022-12-07 and the only framework-compat work ever shipped. Before adopting, open composer.json:

• If it reads symfony/*: ^6.2, that permits 6.3/6.4 but not Symfony 7 — plan accordingly.
• Symfony 6.2 itself is long past end-of-life, so "supports 6.2" is not the same as "supports your stack."
• The release is a patch bump (0.2.2 → 0.2.3) carrying a compatibility change. That is a versioning smell; diff the constraints yourself rather than trusting the number.

Still near-dormant. Two-and-a-bit years between releases, 9 stars, 0 dependents, 0.x versioning. You are the maintainer of anything you adopt here. Budget the fork on day one rather than after the first breakage.

Silent no-ops. Filters that receive a null/absent parameter frequently do nothing rather than throwing. Always test the negative case: assert the SQL is unchanged when the param is missing, so you notice when the filter is silently broken after an upgrade. This matters more now — going from Symfony 5 to 6 means the DI/service-definition plumbing changed underneath filters that previously worked.

Joins and duplicate rows. Filters that add joins can multiply result rows. Watch for it in the profiler; fix with ->distinct() or a correlated EXISTS subquery rather than groupBy (which tends to break pagination counts).

Config caching. Symfony caches the compiled container; Laravel caches config. A change that "doesn't take" is nearly always a stale cache — bin/console cache:clear / php artisan config:clear should be step one of every debugging session. After the 6.2 upgrade especially, clear the cache before concluding the bundle is broken.

Debugging toolkit. debug:config <alias> for resolved config, debug:container --tag=<tag> to confirm the filter services registered, and the profiler's Doctrine panel (or DB::listen in a Laravel port) to see actual SQL. $qb->getSQL() with $qb->getParameters() beats reading source.

Extension points. The filter classes are the seam — subclass or decorate via Symfony's decorator pattern instead of editing vendor/. Editing vendor is guaranteed to be lost on the next composer install and will not survive the fork.

Contract test. Add a small test that asserts each filter produces the expected SQL fragment against a fixture entity. It is the only thing that will tell you when a dependency bump silently changes filter semantics — and given the release history, the next bump will be a surprise.