Laravel Sri Laravel Package

Getting Started

• Install: composer require <vendor>/<package>:^3.5. Version 3.5.0 is the first line that declares Laravel 13 support, so if you're on Laravel 13 this is your minimum constraint; on Laravel 11/12 any 3.x release will do.
• Look here first, in order:
  1. composer.json — check the illuminate/support / illuminate/contracts constraints and the extra.laravel.providers entry that drives auto-discovery.
  2. README.md — the canonical quickstart; the install snippet is usually the only thing that changes between minor releases.
  3. src/ServiceProvider.php — tells you what is bound into the container, what is publishable, and which config keys actually exist.
  4. CHANGELOG.md / PR #106 — confirm whether the Laravel 13 bump also relaxed or tightened any dependency constraints.
• First use case: install into a scratch Laravel 13 app, run php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (or --tag=package-config), set the env vars the config file references, then exercise the package's headline feature once in php artisan tinker. Validate the integration end-to-end before touching your real app.
• Verify the upgrade path: since 3.5.0 only advertises framework compatibility, your smoke test is "does the app boot and does the existing feature still work" — not "did the API change." Run your test suite plus one manual flow.

Implementation Patterns

• Config-over-code: publish the config file and drive behaviour from config/package.php + .env entries rather than calling setters at runtime. This keeps the package compatible with config:cache and makes per-environment behaviour explicit.
• Resolve from the container, don't new: inject the package's contract/class into constructors or resolve via app(...) inside service providers and jobs. That keeps you swappable if you later bind a fake or decorator in tests.
• Bind once, in a dedicated provider: if you wrap the package (recommended for anything non-trivial), create App\Providers\PackageServiceProvider that calls parent::register() semantics, then applies your bindings and macro registrations. Keeps package wiring out of AppServiceProvider.
• Feature-test against the package's own helpers: most Laravel packages ship test macros/traits. Use them plus RefreshDatabase in your own suite so a future 4.x bump surfaces breakage in CI rather than production.
• Queue and event integration: register listeners/handlers that call the package rather than embedding package calls deep in controllers — this is the cheapest way to survive a future major version with a changed method signature.
• Version pinning per app: pin ^3.5 in the app that targets Laravel 13, and keep the constraint wide (^3.0) for shared libraries so downstream apps on Laravel 11/12 are not forced forward. Only the Laravel 13-targeting app needs the 3.5 floor.
• CI matrix: add a Laravel 13 job to your matrix when you bump. The package's own matrix now includes it, but your app's integration layer is what actually breaks.

Gotchas and Tips

• A compatibility release is not automatically a drop-in for your code. 3.5.0 is a minor, so no breaking API change is expected — but the Laravel 13 bump may have moved internal framework APIs the package touches. Read the diff for PR #106; it's usually a few lines of composer.json plus test-matrix changes.
• Don't upgrade for the sake of it. If you're on Laravel 12, 3.5.0 buys you nothing. Upgrade when you move the framework, and do both in the same branch so you can bisect a single change.
• Constraint resolution traps: a package bumping illuminate/* to ^10|^11|^12|^13 can silently pull in a newer transitive dependency. Run composer update --dry-run first, and commit composer.lock for apps.
• Auto-discovery plus config:cache: if bindings behave differently between php artisan serve and a cached deploy, you almost certainly registered something conditionally in a provider that runs before config is available. Check php artisan about and clear with php artisan optimize:clear.
• Publishable assets are snapshots: vendor:publish won't overwrite existing files, so a 3.5.0 config change (if any) won't reach you. Diff vendor/.../config/package.php against config/package.php after every minor bump; use --force deliberately, never habitually.
• Debugging: enable the package's own log channel rather than dumping inside its code — you'll lose your edits on the next composer install. Use Log::channel(...) in a wrapper or a listener, and pair with Telescope for query/event inspection.
• Extension points to check before forking: container bindings declared in the provider, Macroable traits on the package's classes, and any dispatched events. Any of these lets you customise behaviour without patching vendor code — and patching vendor code is what will break you at 4.0.
• Watch the deprecation surface, not just the changelog: if 3.5.0 was needed for Laravel 13, then a 4.0 dropping Laravel ≤12 is the likely next step. Track it now so the eventual major is a scheduled migration rather than an incident.