Similar Laravel Package

Getting Started

Release 2.2.0 is a compatibility release, not a feature release: it adds PHP 8 and Laravel 9 support. That means the day-to-day story is mostly about upgrading safely and then using the package exactly as before.

Minimum steps

composer require <vendor>/<package>:^2.2
php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>"

Then confirm the three things that matter:

1. composer show <vendor>/<package> — verify the installed version is 2.2.x and that composer.json constraints actually read "php": "^8.0" and "illuminate/*": "^9.0".
2. php artisan about — confirm the app boots on Laravel 9 without the package's service provider throwing.
3. The published config file — that's your primary lever; read it top to bottom before writing any code.

Where to look first

• The published config file (usually config/<package>.php) — it documents most of the behaviour without reading source.
• The package's service provider — shows what's bound into the container, what's auto-discovered, and which extension points exist.
• The facade (if one is registered) — the fastest read of the public API surface.

First use case

The most valuable first task after upgrading is a smoke test, not a feature: install on a throwaway Laravel 9 app with PHP 8.1, hit the package's main entry point once, and run your existing test suite. If that passes, 2.2.0 is a drop-in and you can defer deeper work.

Implementation Patterns

Upgrade workflow for existing apps

Treat 2.2.0 as a two-variable change (PHP runtime + framework major) and isolate them:

# 1. Runtime first, framework second
composer require <vendor>/<package>:^2.2 --with-dependencies
php -v            # must be 8.0+
php artisan --version

If you're currently on PHP 7.x or Laravel ≤8, you cannot take 2.2.0 alone — the Laravel 9 jump brings Symfony 6 and Flysystem 3 with it. Pin to ^2.1 on the old stack and upgrade the framework in a separate PR.

Dependency injection over facades

Where a facade exists, prefer constructor injection so tests can swap the implementation:

public function __construct(private PackageContract $package) {}

Resolve via the container contract rather than app('package') string lookups — string bindings are the first thing to break across majors.

Config-first, env-second

Put deployment-specific values in config/<package>.php reading from env(), never call env() directly from application code. When you cache config in production (php artisan config:cache), direct env() calls return null — a classic post-upgrade false alarm.

CI matrix

Because 2.2.0 is explicitly a compatibility release, encode the supported combinations:

php: ['8.0', '8.1']
laravel: ['9.*']

Run the package's path in your suite under both PHP versions. If you maintain other apps still on 2.1.x, keep a second job on laravel: 8.* so the constraint ^2.1|^2.2 stays honest.

Queued work

If the package dispatches jobs or listens to events, re-check after the upgrade that workers are restarted (php artisan queue:restart) — serialized payloads from before the upgrade can reference classes whose signatures changed under PHP 8.

Gotchas and Tips

Verify the constraint, don't trust the changelog

"Support Laravel 9" is only true if composer.json allows it. Check for "illuminate/support": "^8.0|^9.0" — a package that says it supports Laravel 9 but pins ^8.0 will silently resolve to an older version and you'll debug a bug that was already fixed.

PHP 8 raises things that used to be silent

• Passing null to non-nullable internal function parameters is now deprecated — expect notices from third-party code the package wraps.
• Stricter type juggling surfaces TypeErrors that PHP 7 coerced away. If you get a TypeError from inside the package, check what you're passing, not the package.
• Named arguments mean a parameter rename is now a breaking change. If you use them, pin tightly.

Laravel 9 specifics that bite adjacent code

• ->change() on migrations needs doctrine/dbal again — unrelated to this package but often discovered in the same upgrade PR.
• The lang directory moved to the root; resources/lang overrides may stop applying.
• Flysystem 3 changed Storage method signatures; anything the package writes to disk is worth an explicit test.

Debugging checklist

1. php artisan about and php artisan package:discover — is the provider registered at all?
2. Clear caches: config:clear, cache:clear, route:clear. Stale cached config after a version bump is the single most common false positive.
3. composer why-not <vendor>/<package> 2.2.0 — shows which of your other dependencies is blocking the upgrade.
4. Reproduce on a bare Laravel 9 skeleton before debugging inside your app; it separates package issues from integration issues.

Extension points

• Bind your own implementation of the package's contract in a service provider rather than subclassing — the container binding survives minor releases better than inheritance.
• Listen to the package's events (if published) instead of overriding internals; events are closer to a public API than protected methods.
• Keep local modifications out of vendor/. If you need a behavioural change, wrap the package behind a thin adapter class of your own so the next compatibility bump is a one-file diff.

Pin and schedule

Given this is purely a support-matrix release with no feature surface change, use "^2.2" and add a calendar reminder to re-evaluate when Laravel 10 support lands — that release is where deprecations will actually appear.