Getting Started

Treat v3.0.0 as a PHP 8.1+ baseline. First confirm your app, CI, Docker image, and local runtime all use PHP 8.1 or newer.
Look first at the package’s composer.json constraints, changelog/upgrade notes, service provider registration, publishable config, and migrations.
First use case: install ^3.0 in a fresh Laravel app on PHP 8.1, publish any config/assets, run migrations if applicable, and execute a minimal smoke test. For existing apps, upgrade on a branch and run the full test suite before merging.

Implementation Patterns

Upgrade workflow: switch runtime to PHP 8.1, run composer update <package> --with-dependencies, then composer check-platform-reqs, php artisan about, and php artisan test.
Keep package config environment-driven. Publish config only when overriding defaults, and rebuild config cache during deploy only after verifying the upgrade.
Add CI coverage for PHP 8.1+ across your supported Laravel versions. Include a --prefer-lowest dependency job to catch constraint issues early.
Verify Laravel integration points: package auto-discovery, facades/aliases, queues, events, scheduled commands, migrations, and any published service-provider bindings.
If the package exposes extension points, rebind interfaces/classes in your app provider only after confirming v3 method signatures and return types are compatible.

The main breaking change is dropping PHP below 8.1. Composer may silently resolve an older major version on PHP 8.0, so pin ^3.0 only in PHP 8.1+ environments.
Use composer why-not php 8.1 to find transitive dependency blockers. Watch for platform config in composer.json masking the real runtime.
PHP 8.1 deprecations can appear as noisy logs. Run tests with deprecations visible and address null-to-non-nullable internal calls, return type mismatches, and serialization warnings.
After upgrading, clear cached state with php artisan optimize:clear, then rebuild caches in staging before production.
Debug failures by comparing composer show <package> across working/failing environments, checking Laravel version constraints, and running the package’s tests against your app matrix.
If overriding package internals, confirm signatures after v3 and avoid relying on undocumented classes or traits that may have changed with the PHP 8.1 baseline.