Filterable Laravel Package

Getting Started

This package now supports Laravel 12 as of 2.1.7. If you are on Laravel 11 or below you can adopt it without changes; if you are on Laravel 12, this is the first release line you can safely pin to.

Minimal steps

1. Require it with a constraint that keeps you on the Laravel 12-compatible line:

   composer require <vendor>/<package>:"^2.1"
   

   Pin to ^2.1 rather than ^2.0 — earlier 2.x releases predate Laravel 12 support and Composer will happily resolve them if your lock file is stale.
2. Confirm the resolved version and that dependencies agree:

   composer show <vendor>/<package>
   composer why illuminate/support
   

3. Publish anything the package ships:

   php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"
   

   Use --tag= if the README documents tags; publishing everything often drops files you will never touch.
4. Clear cached config before your first run — a stale bootstrap/cache/config.php is the single most common reason a fresh install "does nothing":

   php artisan config:clear && php artisan optimize:clear
   

Where to look first

• config/<package>.php (after publishing) — this is the contract surface. Read every key before writing code; most "the package won't do X" issues are a config default.
• The service provider — it tells you what is bound into the container, what is auto-discovered, and which extension points exist.
• composer.json — check the php floor and the illuminate/* constraints. Laravel 12 support is only meaningful if your PHP version satisfies it.
• The package's own test suite (if shipped) — the fastest way to see idiomatic usage rather than README-level usage.

First use case

Do the smallest end-to-end pass in tinker before touching application code:

php artisan tinker
>>> app(<Vendor>\<Package>\<MainClass>::class)

If that resolves, the container wiring is correct and any remaining problem is configuration or usage, not installation. Then wire it into exactly one controller or job and observe it under real request lifecycle (middleware, auth, config cache) before rolling it out.

Implementation Patterns

Resolve from the container, don't instantiate. Prefer constructor injection or app() over new. The package likely reads config and collaborators at construction; new bypasses both and silently ignores your config file.

Wrap it in a thin application-level adapter. Even a 20-line App\Support\<Thing> class that delegates to the package pays for itself the first time you swap versions or need to fake it in tests. It also stops package-specific types from spreading across your codebase — the difference between a one-file upgrade and a week of grep-and-replace.

Keep configuration in config/, secrets in .env. Set env-backed values in the package config file ('key' => env('PACKAGE_KEY')) rather than calling env() in application code — env() returns null once config:cache has run in production.

Queues and long-running processes. If the package does work in jobs or listeners:

• Confirm the payload is serializable (no closures, no container references) before dispatching to a real queue driver — sync hides serialization failures.
• Restart workers on every deploy: php artisan queue:restart. Code changes are invisible to already-running workers.
• Check whether the package reads config at boot or per-job. Boot-time reads mean a config change needs a worker restart, not just a deploy.

Use the package's own hooks before forking behaviour. Look for an extend()/manager pattern, macros, or events. Registering a custom driver through the package's extension point survives minor upgrades; subclassing internals does not.

Testing. If the package ships fakes or assertion helpers, use them — they usually handle the container rebinding correctly. If not, bind a mock in a test service provider rather than mocking the facade, and add one integration test that hits the real implementation so a minor version bump fails loudly in CI instead of in production.

Build a version matrix in CI. With the 2.1.x line, run your suite against Laravel 12 at minimum; if you support both 11 and 12, add both to the matrix so a future patch release can't silently break the older one.

Gotchas and Tips

• "Supports Laravel 12" is a statement about this package, not your app. Your other dependencies may still cap illuminate/* at 11. Run composer why-not laravel/framework 12.* before planning an upgrade — it names the blocking packages directly.
• Check the PHP floor. Laravel 12 requires PHP 8.2+. If the package raised its own minimum in the 2.1 line, your CI image and any older runtime need attention before the composer bump.
• Auto-discovery vs. manual registration. Laravel 12 continues package discovery, but if you have a cached bootstrap/cache/packages.php from a previous install the new provider may not register. php artisan package:discover after upgrading.
• Never edit vendor/. Re-publish with --force only when you have diffed the config first — the 2.1 line may have added keys, and --force silently overwrites your customisations.
• Debug config before debugging code. php artisan config:show <package> tells you what the app actually sees. Nine out of ten "it ignores my setting" reports end here.
• Read the 2.x changelog for deprecations, not just the release note. "Added support for Laravel 12" releases frequently ride alongside quiet removals of deprecated methods. Grep your codebase for any package symbols you use before bumping.
• Pin patch versions in composer.lock, review minors deliberately. Patch releases in this line should be compatibility-only, but treat any 2.1.x → 2.2.0 as a reviewable change rather than an auto-merge.
• Falling behind is the real risk. If your app is on Laravel 12 and you are still on a 2.0.x pin, you are on a line that was never tested against your framework — upgrade to ^2.1 before adding features on top of it.