Lastus Laravel Package

Getting Started

The v5.0.0 release note is a single line — "Support Laravel 10" — so treat this as a compatibility release with an unstated blast radius. The major version bump is the signal: 5.0.0 is allowed to break things, and the note does not enumerate what. Before changing anything in your app, read the package's CHANGELOG.md and, if present, UPGRADE.md for the 4.x → 5.0 diff, then diff the package's own composer.json between the tags.

Minimal steps:

1. Confirm the constraint: composer require vendor/package:"^5.0". Check the package's composer.json for php and illuminate/* constraints — Laravel 10 implies a PHP ^8.1 floor, so your runtime and CI image must already be on 8.1+.
2. Verify discovery: the service provider should be picked up by package auto-discovery. If it isn't listed under extra.laravel.providers, register it manually in config/app.php (or bootstrap/providers.php if you've adopted the newer skeleton convention).
3. Publish and inspect assets before writing code: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (or --tag=package-config). Read the published config file top to bottom — it is usually the most accurate documentation the package ships.
4. Run php artisan about and composer show vendor/package to confirm the resolved version and that no other dependency is holding you on 4.x.

First use case: exercise the package's primary entry point in isolation — typically a single facade call, a trait added to one model, or a middleware added to one route group — in a scratch route or a php artisan tinker session. That confirms autoloading, config resolution, and credentials before you wire it into anything else. Where to look first in the source: src/ root for the facade and service provider, config/ for defaults and env keys, database/migrations/ if it ships schema, and tests/ for executable examples of intended usage.

Implementation Patterns

Config-first, always. Resolve everything through the published config file and reference env vars only from there. This is what makes config:cache safe in production and what lets you run different settings per environment without touching vendor code.

Prefer constructor injection over the facade in services, jobs, and listeners. The facade is fine in controllers and Blade, but DI makes the dependency swappable in tests and keeps the coupling visible. If the package ships a facade, it almost certainly has a matching container binding you can type-hint.

Wrap third-party surface area. Put the package behind a thin application-level service (e.g. App\Services\X) rather than calling it from twenty places. When 5.x turns out to have a renamed method or changed default, you edit one file. This matters more than usual on a major bump whose changelog you don't fully trust.

Pin and stage the upgrade. Bump the constraint to ^5.0 on a branch, run the full suite, then ship. Keep ^4.0 available in composer.json history so a rollback is a one-line revert rather than a bisect. If you maintain packages that depend on this one, widen to ^4.0|^5.0 only after your own matrix passes on Laravel 10.

Test against the real container. Use RefreshDatabase if the package ships migrations, and use the package's own fake/swap helper if it exposes one (Package::fake() is a common convention) rather than hand-rolling mocks. If there's no fake, $this->mock(Contract::class) against the bound interface is the fallback.

Queue and event integration. If the package dispatches events or offers queued jobs, register listeners in a dedicated EventServiceProvider entry and verify serialization — a config object or closure captured in a job payload will fail on the queue worker even when it passes in a synchronous test.

CI matrix. Run Laravel 9 and 10 (and the corresponding PHP versions) in parallel until you've dropped 9. The "Support Laravel 10" line says nothing about 9 being dropped, so verify rather than assume.

Gotchas and Tips

• Major version ≠ compatibility-only. The note mentions Laravel 10; semver permits unrelated breaking changes in the same release. Assume method signatures, config keys, and defaults may have moved until the changelog proves otherwise. Grep your codebase for the package namespace after upgrading and read every call site.
• PHP 8.1 floor. Laravel 10 requires PHP 8.1, so this package now effectively does too. Docker base images, CI php-version, and any platform.php override in composer.json are the usual culprits when resolution mysteriously fails.
• composer why-not vendor/package 5.0 is the fastest way to find which sibling dependency is still pinning an older illuminate/support. Don't start deleting constraints until you've read that output.
• Cached config. env() called outside config/ returns null once config:cache has run. If the package reads env directly, it will appear to work locally and silently misbehave in production. Check src/ for env( before you trust it.
• Re-publishing overwrites. vendor:publish --force will clobber your customized config on upgrade. Diff the new default config against your published copy manually instead.
• Laravel 10 removals. Deprecated model $dates, the doctrine/dbal requirement for column modifications, and several older string/helper APIs are gone. If the package touches schema or models, that's where a real 5.0.0 break is most likely hiding.
• Debugging order: php artisan about → composer show → config('package.key') in tinker → package's own test suite (vendor/bin/phpunit in the package dir if you have a path repository) → storage/logs/laravel.log. Most "the package is broken" reports resolve at step three.
• Extension points to prefer: container bindings and interfaces over subclassing concrete classes, published config over reflection into package internals, and events/listeners over monkey-patching behavior. Anything you reach into with reflection is a guaranteed 6.0.0 break for you.