Getting Started

Check the version gate first. v4.0.0 requires PHP 8.3+ and Laravel 13. If your app is still on PHP 8.2 or Laravel 11/12, stay on the v3 line — nothing in this release is available to you. Confirm your composer.json php constraint and laravel/framework constraint before touching the lockfile.
Install/upgrade: composer require vendor/package:^4.0. For existing installs, run composer update vendor/package --with-dependencies on a branch and read the diff of the published config file (if the package ships one) — v4 is a major, so treat any config or migration stubs as potentially changed.
Where to look first: the package's UPGRADE.md / changelog for the v3→v4 delta, then the service provider to see what is bound into the container and which config keys it reads. That tells you far more about day-to-day behaviour than the README.
First use case: pick the single highest-traffic call site (one controller, one job, one listener), wire the package in there only, and verify with a feature test plus a quick php artisan tinker sanity check before rolling it across the codebase.
CI is part of the upgrade. Bump the PHP matrix to 8.3/8.4 and add a Laravel 13 job. This release is a platform-support bump, so the real risk is your pipeline silently testing an unsupported combination.

Implementation Patterns

Constructor injection over facades. Resolve the package's main service through the container so you can swap it in tests; keep facade usage for one-off calls in Blade or Artisan commands.
Wrap it, don't sprinkle it. Put the package behind a small first-party interface or adapter class. That is what made this upgrade cheap for teams that did it — the third-party surface area is one file, not forty.
Config-driven integration. Publish the config, commit it, and read values via config() rather than hardcoding. Keep environment-specific values in .env and reference them from the config file.
Queue boundary. If the package performs I/O, invoke it from a queued job with an explicit $tries/$backoff rather than inline in a request. This also isolates failures during the upgrade.
Testing. Use the package's fake/swap hooks (if provided) in setUp(); otherwise bind a mock of your adapter. Add at least one integration test that exercises the real package against a test database so a major bump can't pass green while silently no-op'ing.
Upgrade workflow: branch → composer update → run php artisan config:clear → full test suite → smoke test staging → merge. Run composer why-not vendor/package 4.0.0 if resolution fails; it names the exact conflicting constraint.

PHP 8.3 is a hard floor, not a suggestion. Composer will refuse to install on 8.2. Docker images, Forge/Envoyer/Vapor runtimes, and local Herd/Valet PHP versions all need bumping — this is the most common cause of a "failed" upgrade.
Laravel 13 support ≠ Laravel 12 support. If a dependency pins laravel/framework:^12, composer why-not will surface it. Expect to upgrade transitive packages in the same pass.
Config caching bites on major upgrades. After deploying v4, run php artisan config:clear (and optimize:clear) — stale cached config referencing removed keys produces confusing null errors that don't reproduce locally.
Silent deprecation removal. Majors often drop previously-deprecated methods without a loud error (deprecation notices were the warning). Grep your codebase for any package method you call and confirm it still exists in the v4 source.
Lock file drift in CI. Commit composer.lock; otherwise a fresh CI run may resolve a different patch and mask or introduce failures.
Extension points. Before forking, check whether the package exposes a manager/repository binding or an events layer you can hook into — most Laravel packages let you override the concrete class via $app->bind() in a service provider rather than editing vendor code.
Pin it. Use ^4.0 and let patch releases flow, but pin to 4.0.* for the first few weeks if this package sits on a critical path.