Getting Started

Treat 4.0.0 as a platform-compatibility major, not a feature release. The day-to-day API is expected to be unchanged; the work is in your runtime matrix.
First check composer.json for the exact PHP and Laravel constraints. The release drops Laravel 9 and PHP 8.0–8.1, so 4.x requires a newer PHP floor and supports Laravel 13.
For a new app: require ^4.0, publish only the config/migrations you actually need, and wire the package into one narrow path first (a single controller, job, or middleware) before rolling it out.
For an existing app: read the upgrade guide/changelog, then run composer why-not vendor/package 4.0.0 to identify platform or dependency blockers before changing code.
First useful use case: validate the upgrade in CI on your oldest and newest supported Laravel/PHP combinations, then exercise the package’s primary workflow in a staging branch.

Implementation Patterns

Pin new projects to ^4.0 and keep existing Laravel 9 / PHP 8.0–8.1 projects on the previous major until the platform is upgraded.
Use Composer constraints rather than --ignore-platform-reqs. If Composer blocks the upgrade, fix PHP or Laravel first; forcing the install only moves the failure to runtime.
In application code, keep package usage behind your own service, action, or job boundary where practical. That makes future major upgrades and test doubles easier.
Publish config only when overriding defaults. Prefer environment variables and config keys over editing vendor files.
During upgrade: update the package, run migrations, clear cached config/routes/views, then run the full test suite. Pay special attention to package discovery and service-provider registration.
In CI, test the lowest and highest supported Laravel/PHP combinations. Laravel 13 support is only meaningful if your test matrix actually covers it.
For integrations, prefer the package’s documented facade/helper or dependency-injected services, and use its events/extension points instead of patching internals.

Breaking platform changes: Laravel 9 and PHP 8.0–8.1 are no longer supported. This is the main upgrade risk; application code may be compatible while Composer still refuses the update.
Laravel 13 support can cascade: dev dependencies such as PHPUnit, Pest, Collision, and static-analysis tooling may also need updates before the test suite runs cleanly.
Published assets may drift: if you published config or migrations under 3.x, diff them against 4.x defaults. Republishing with --force can overwrite local customizations.
Debugging checklist: composer show vendor/package, php artisan about, php artisan package:discover, and php artisan config:clear quickly reveal version, provider, and cached-config problems.
Extension points: use published config, container bindings, events/listeners, and documented macros before reaching for vendor patches.
No feature reason to rush: because 4.0.0 is primarily compatibility work, upgrade when you need Laravel 13 or newer PHP support—not just to get a new API.