Getting Started

Verify your app targets PHP 8.0+ and Laravel 9.x; 2.2.0 is the compatibility release that adds support for both. If you are still on PHP 7.x or Laravel 8, stay on the previous 2.x line until you upgrade.
Install with composer require vendor/package:^2.2 and check composer.json for extra.laravel.providers / extra.laravel.aliases. If present, Laravel auto-discovery registers the package; otherwise add the service provider in config/app.php.
Publish any package config or assets with php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider" and review the published config before writing code.
First use case: integrate the package into one isolated feature (a single controller, command, or job) and confirm it behaves correctly on PHP 8/Laravel 9 before rolling it out across the app.

Implementation Patterns

Resolve the package's primary class from the container rather than instantiating it directly with new; this keeps you insulated from constructor changes in future 2.x releases.
If the package ships a facade, use it in controllers and views but prefer constructor injection in services, jobs, and listeners so the dependency is explicit and easy to fake in tests.
Bind package contracts/interfaces in your own service provider when the package exposes them. This lets you swap in test doubles or decorate behavior without touching vendor code.
Keep environment-specific values in the package's config file and reference them through config(). Avoid hard-coding values the package expects to read from configuration.
If the package dispatches jobs or events that depend on database state, use afterCommit() or Laravel's DB::afterCommit() to avoid race conditions in queued workflows.
Add a CI smoke test that runs on PHP 8 and Laravel 9. A single test that boots the package and exercises its main entry point will catch most compatibility regressions early.
Prefer listening to the package's events over extending its core classes. Events are a more stable extension point across minor releases.

PHP 8: watch for deprecations around optional parameters declared before required ones, dynamic properties, and union/nullsafe type interactions. Run composer why-not php 8.0 to confirm no transitive dependency blocks the upgrade.
Laravel 9: verify compatibility with Flysystem 3, Symfony Mailer, and anonymous migrations if the package touches storage, mail, or database schema. These are the most common sources of breakage in Laravel 9 upgrades.
Auto-discovery can hide a missing service provider if you support multiple Laravel versions. If your package is used across Laravel 8 and 9, register the provider explicitly and test both paths.
Config caching is a frequent source of "works locally, fails in CI" bugs. After changing package config, run php artisan config:clear and confirm the cached config includes your values.
Debugging: enable the package's own logging/debug channel if it provides one; otherwise wrap calls with Log::debug() or inspect them in Telescope to see inputs and outputs.
Extension points: look for macros, custom drivers, or published config before forking. Most Laravel packages expose these specifically to avoid vendor patches.
Pin to ^2.2 and watch the 2.x changelog for follow-up patch releases; compatibility releases often receive small fixes for PHP 8 edge cases after the initial rollout.