Laravel Nhif Laravel Package

Getting Started

• Install with composer require <vendor>/<package> and confirm the resolved version is ^2.2. The 2.2.0 release only widens the framework constraint (Laravel 13 / testbench 11.*), so any 2.x install path you already had still applies — you are not learning a new API, you are just clearing the version gate.
• Check composer.json for the PHP floor before upgrading. Laravel 13 + testbench 11 pulls a newer PHPUnit/PHP baseline into your dev dependencies; if your app is pinned to an older PHP minor, composer update will resolve back to 2.1.x and you will silently not get Laravel 13 support.
• First place to look is the README quickstart, then the package's service provider. The provider tells you what is bound into the container, what is registered as a singleton, and which config keys are actually read — that is the contract you will be coding against day to day.
• Publish assets before writing any code: php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>" (or --tag=<package>-config if the package defines tags). Commit the config file, then override environment-specific values in .env rather than editing the published file per environment.
• First real use case: write one feature test that boots the package and exercises the happy path before you wire it into application code. If the package ships testbench support (it does — that is what the 11.* bump is for), mirror its TestCase setup so your test boots the same provider set the package's own CI does.

Implementation Patterns

• Depend on the container binding, not the concrete class. Resolve the package's entry point through the container (constructor injection or app(...)) so test doubles, decorators, and future major versions can swap the implementation without touching call sites. Type-hint the package's interface/facade-backed contract where one exists.
• Bind overrides in your own service provider, not in the package's. Register your custom implementation in AppServiceProvider::register() (or a dedicated provider listed after the package provider in bootstrap/providers.php) so package updates never clobber your wiring.
• Config-first integration. Anything the package exposes as config — drivers, queue names, table names, retry counts — belongs in config/<package>.php committed to the repo, with secrets and per-environment toggles in .env. Avoid calling setters at runtime; it makes behaviour invisible to config:cache and to anyone reading the repo.
• Wrap it, don't sprinkle it. If the package is used in more than two or three places, put a thin application-level service in front of it. This is the single highest-leverage pattern: it isolates you from a future 3.0, gives you one place to add logging/metrics, and makes the dependency fakeable in tests without touching the package internals.
• Testing. Use the package's own fakes/mocks where provided; otherwise bind a stub in the container inside setUp(). For queue or event integration, prefer Bus::fake() / Event::fake() over hitting the package's real transport — the former is fast and version-stable.
• CI mirroring. Since 2.2.0 is explicitly a compatibility release, mirror the package's matrix in your own pipeline: run one job on the lowest Laravel version you claim to support and one on the highest. A green build on Laravel 13 alone hides the fact that you dropped 11.x behaviour.
• Upgrade workflow for consuming apps. Bump the constraint in a branch, run composer update <vendor>/<package> --with-dependencies, then php artisan config:clear && php artisan cache:clear, then the full suite. For a release like 2.2.0 the expected diff is zero — if you see behavioural changes, suspect a transitive dependency bump rather than the package itself.

Gotchas and Tips

• "Supports Laravel 13" is not "requires Laravel 13." Verify the constraint actually reads something like illuminate/support: ^10.0|^11.0|^12.0|^13.0. If the maintainers narrowed it, your Laravel 11/12 apps will fail to resolve on the next composer update — check composer why-not before assuming it is your app's fault.
• testbench 11.* is a dev-only bump. It should not appear in require, only require-dev. If it leaks into production requirements you will drag testing utilities into your deploy artifact.
• Config caching bites hardest here. Any env() call made outside a config file returns null once config:cache has run. If the package reads env directly, set the values in the published config file and treat the env var as the source for that file only.
• vendor:publish --force overwrites silently. Before re-publishing after an upgrade, git diff the published config against the package's config/ stub — new keys added in a minor release are the usual cause of "why is this option ignored."
• Service provider ordering matters. If your override is registered before the package provider, the package's binding wins. Confirm order in bootstrap/providers.php (Laravel 11+) and remember package Discovery happens before app providers are booted.
• Queued work serialises your objects. If you pass a package object into a job constructor, it must be SerializesModels-safe and reconstructible after a deploy. Pass IDs and re-resolve from the container inside handle().
• Debugging resolution. app()->make(...) inside tinker, plus php artisan about to confirm the provider is loaded, resolves most "class not found / binding missing" reports faster than reading the stack trace. For deeper inspection, bind a logging decorator around the contract temporarily.
• Extension points to prefer, in order: config values → container bindings → published views/migrations → package events → macros (if the package registers them). Avoid subclassing package classes; minor releases routinely change protected members, and 2.2.0 proves the package is willing to move its framework floor under you.
• Pin the minor, not the patch. "<vendor>/<package>": "^2.2" gives you compatibility fixes without absorbing an unannounced 2.3 feature release mid-sprint; an exact pin will leave you stranded when the next Laravel version lands.