Invytr Laravel Package

Getting Started

This is a compatibility/maintenance release: 1.0.11 widens runtime support to Laravel 11 & 12 and PHP 8.3 & 8.4. The patch-level version bump plus compatibility-only notes signal no API break — treat it as a "can I run this on my stack?" release rather than a feature release. Everything below is scoped to that: getting the package booted on a modern Laravel stack and confirming it behaves before you build on it.

Minimal steps:

1. composer require <vendor>/<package>:^1.0.11 — the explicit patch floor matters if you need the Laravel 12 / PHP 8.4 fixes specifically; ^1.0 is fine if you were already working on 11/8.3.
2. Read the package's composer.json before anything else. Confirm the illuminate/* (or laravel/framework) constraint actually admits ^11.0|^12.0 and the php constraint admits ^8.3|^8.4. Release notes describe intent; the constraint file is the contract.
3. Check auto-discovery: extra.laravel.providers and extra.laravel.aliases in the package's composer.json. If present, no manual provider registration is needed on 11/12.
4. Publish and inspect config if the package ships any: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag=config.
5. Smoke test the thinnest possible integration — resolve the package's entry class from the container (app(\Vendor\Package\Client::class) in tinker) or hit the one route/command its README shows. Do this on Laravel 12 + PHP 8.4 first, since that's the newest supported combination and the most likely to surface lifecycle issues.

First real use case: pick your lowest-risk consumer (a console command, a scheduled job, or a single controller action) and wire the package in there before touching anything in the request path.

Implementation Patterns

Prove the support matrix in CI, not in production. Add a test matrix of PHP 8.3, 8.4 × Laravel 11.*, 12.*. If you're testing the host app rather than the package, run the suite twice against laravel/framework:^11.0 and ^12.0 via composer update -W. For package-level work, orchestra/testbench with matching major versions is the standard harness.

Isolate the package behind a seam. A thin wrapper — an interface plus one adapter class bound in a service provider — costs an hour and means the next major bump is a single-file change. This matters more than usual here: a package jumping from "Laravel 10-era" to "11 & 12" is a signal the maintainer is actively tracking framework majors, so another one is likely. Don't let the package's facade or model classes leak into domain code.

Ship the upgrade in its own commit. Widening the composer constraint and bumping the lockfile should be a standalone PR that touches no application logic. When something breaks you'll know it was the version, not your refactor. Follow with a second PR that only removes now-unnecessary compatibility shims.

Drive behaviour through published config and env, never vendor edits. Publish once, commit the config file, and read values from config('package.key') with env fallbacks in the config file itself. Never edit vendor/.

Respect Laravel's event/listener seams. If the package dispatches events or queues jobs, register listeners in your own EventServiceProvider/AppServiceProvider and point the package's config at your listener class — don't rely on the package's internal callbacks, which are the most likely thing to shift between majors.

Re-verify singletons under long-running workers. If you run Octane, Horizon, or long-lived queue workers, confirm the package holds no per-request state in a singleton after the upgrade. Laravel 11 changed several container and lifecycle defaults; a package that was fine under 10's request model can leak state under 11/12.

Gotchas and Tips

The lockfile won't move on its own. A patch bump that only widens constraints can leave composer.lock untouched — you'll think you're on 1.0.11 while actually resolving an older build. Run composer update <vendor>/<package> -W and confirm with composer show <vendor>/<package> before concluding the release doesn't fix your problem.

PHP 8.4 makes deprecation noise loud. Implicitly-nullable parameters (string $x = null without ?string) are the big one. If your test suite suddenly emits E_DEPRECATED after the bump, that's the package (or a transitive dep) not 8.4-clean — treat it as signal, not noise to suppress. Fix the suite's error reporting to surface deprecations rather than swallow them.

Laravel 11 removed app/Http/Kernel.php. If the package's docs tell you to register middleware or route middleware in the HTTP Kernel, translate that to bootstrap/app.php → ->withMiddleware(function (Middleware $middleware) { ... }). Stale README instructions are the most common source of "the package is broken" reports after a major bump; the package is usually fine.

Model and cast conflicts on Laravel 11/12. If the package ships Eloquent models, check for a casts() method conflicting with a $casts property, and for $dates (removed). These are silent-ish failures — the model loads but dates come back as strings.

Auto-discovery can be off in the host app. extra.laravel.dont-discover in your composer.json silently skips the provider. If the package appears to do nothing at all, that's the first place to look — before you start debugging the package.

Config cache is a trap after publishing. php artisan config:cache bakes in whatever was in config/ at cache time; package defaults merge during boot. If config changes seem to have no effect, php artisan config:clear before re-testing, and always clear in your deploy pipeline after a dependency bump.

Debugging commands worth having in muscle memory: php artisan about (framework/PHP versions as Laravel sees them — catches mismatches between CLI and FPM), php artisan package:discover -v (shows what registered and what failed), and composer why-not laravel/framework 12.* (tells you exactly which constraint is holding you back, which is often a sibling package rather than this one).

Extension points, in order of stability: published config → container bindings → dispatched events → public class extension. Stay in the first three. Subclassing vendor classes is the thing that turns a patch upgrade into a rewrite.