Laravel Healthcheck Laravel Package

Getting Started

Version 4.0.0 is a framework-compatibility release: it adds Laravel 10 support. Treat it as an upgrade task rather than a feature drop — there is no new API surface described in the notes, so the work is validating that your existing integration still behaves identically on Laravel 10.

1. Check the constraints before touching code. Inspect composer.json for illuminate/*, php, and any dev-dependency pins. A 4.0.0 major bump on a Laravel 10 release almost always means Laravel 8/9 and PHP 8.0 have been dropped from the require block. Confirm your app's php and laravel/framework versions satisfy them, then run composer why-not vendor/package ^4.0 to see exactly what is blocking resolution.
2. Read the service provider first. It is the fastest way to learn what the package registers: config merges, singletons, facades/aliases, migrations, and publishable assets. Anything registered there is something your upgrade can break.
3. Publish and diff the config. Run php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider" --tag=config on a scratch branch and diff against your committed config. Major versions routinely rename or drop keys, and a silently missing key is the most common post-upgrade failure.
4. Run php artisan about and php artisan package:discover after the update to confirm the provider registers cleanly on Laravel 10 before you debug any application logic.

First use case: pick the single highest-traffic code path that touches this package (one controller, one job, one listener), get it green on the new version, then widen. Do not attempt a whole-app upgrade in one pass on a package you have not yet verified.

Implementation Patterns

Upgrade in an isolated branch with the test matrix widened, not replaced. Keep the old lockfile reachable so you can bisect. The practical workflow is: bump the constraint, composer update vendor/package --with-dependencies, run the suite, then read the diff of what Composer actually changed — transitive bumps to illuminate/support or symfony/* are frequently the real cause of a failure, not the package itself.

Resolve the contract, don't reach for the facade. Inject the package's interface or concrete class via the container. This is the pattern that makes a future major version cheap: when a method signature changes, you fix one binding or one adapter instead of grepping for Package:: across the codebase.

// app/Services/Billing/InvoiceGateway.php
final class InvoiceGateway
{
    public function __construct(private readonly PackageClient $client) {}

    public function charge(Order $order, int $cents): Receipt
    {
        return $this->client->createCharge($order->id, $cents);
    }
}

Wrap the package behind a thin application-level adapter. Even a 30-line wrapper around the two or three methods you actually call buys you a single place to absorb breaking changes, add logging, and swap implementations in tests. It also stops package-specific types leaking into your domain layer.

Configure through config/, not env(). Call env() only inside your published config file. After any config change run php artisan config:clear (and config:cache in the deploy pipeline) — stale cached config survives composer update and produces failures that look like upgrade regressions but are not.

Fake or swap the package in tests. If it exposes a fake, use it in setUp(). If not, bind a test double against the interface in a dedicated service provider registered from TestCase. Verify a real round-trip in a single integration test rather than in every unit test.

Upgrade Laravel and the package as one deliberate step. Moving to Laravel 10 and moving to ^4.0 in the same PR conflates two failure sources. If your app is already on Laravel 10, the package bump is trivial; if it is not, sequence the framework shift first.

Gotchas and Tips

• "Laravel 10 Support" in a major version implies removals, not just additions. The notes state only the headline. Assume the supported matrix narrowed and treat composer.json in the tag as the authoritative changelog. Diff it against the 3.x tag.
• Read the upgrade guide even when there isn't one. If the release has no UPGRADE/CHANGELOG detail beyond the one line, diff the public API yourself: git diff 3.x..4.0.0 -- src/ filtered to public method signatures, constructor parameters, and config keys.
• Deprecation notices are not errors until they are. Run the suite with E_ALL and a deprecation-to-exception handler on Laravel 10 before shipping; this is where removed illuminate helpers and dynamic-property issues surface, well ahead of them becoming hard failures on the next major.
• Migrations are easy to miss on a compatibility bump. Check whether the package's published migrations changed and whether any new ones need publishing. On a major version, also confirm no existing migration was edited in place — edited historical migrations silently diverge between fresh installs and upgraded environments.
• Dependency conflicts present as unrelated errors. If you get a resolution failure, the constraint is usually a third package pinning illuminate/support below 10. composer why-not and composer depends resolve it faster than reading error output.
• Queued work is the hidden blast radius. If the package serialises models or payloads into jobs, a major version can change that shape. Drain or version your queue around the deploy rather than letting in-flight jobs hit new code.
• Extension points to check before you fork anything: container bindings (rebind a contract to your own implementation), published config and views, driver/manager extend() methods, and any macro or custom-cast registration. Most behavioural customisation should go through one of these rather than a patch.
• Pin and document. Commit the lockfile, note the exact 4.0.x you validated against, and record the Laravel/PHP matrix you tested. The next reader of this upgrade will want that, and the release notes will not give it to them.