Laravel Ui Stisla Laravel Package

Getting Started

v4.0.0 is the first release in this line with Laravel 9 support, which makes it the entry point for any project on Laravel 9 — and a mandatory upgrade for existing installs that need to move. Start by confirming your platform floor: Laravel 9 requires PHP 8.0+, so the package's composer.json will now reflect that. Check it before you touch your lock file:

composer require vendor/package:^4.0
composer why-not vendor/package 4.0   # if resolution fails, shows the blocker

Then locate the integration surface in this order:

1. The service provider — what it binds into the container, what it registers (commands, routes, migrations, Blade components), and whether anything is deferred.
2. The published config file — php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (or --tag=package-config). Read the defaults and every env() call; this is where 80% of behaviour is decided.
3. The contracts/interfaces the package exposes — these tell you what is safe to swap and what is internal.
4. The v3 → v4 diff and CHANGELOG — a major bump that only advertises "Laravel 9 support" in the notes is rarely only that. Look for dropped method signatures, renamed config keys, and removed Laravel 8 shims.

Your first use case should be deliberately small: wire the package into one controller action or queued job, cover it with a single feature test that uses the package's fake or a mocked contract, and confirm it works under php artisan config:cache before rolling it across the codebase.

Implementation Patterns

Resolve from the container, never with app(). Inject the package's contract or facade into constructors and let Laravel resolve it. This is also what makes the package swappable in tests and in multi-tenant setups where the binding changes per request.

public function __construct(private \Vendor\Package\Contracts\Client $client) {}

Keep all configuration in config/package.php, and reference env() only there. If the package reads env() at runtime, it will silently break under config:cache in production — a classic post-deploy incident.

Version-pin in composer.json with a caret, and test both edges. If you still support Laravel 8 alongside 9, run a CI matrix:

matrix:
  laravel: [^8.0, ^9.0]
  php: [8.0, 8.1]

Add one --prefer-lowest leg so you catch a too-loose constraint rather than discovering it in a customer install.

Upgrade as an isolated change. Branch, bump the constraint, run the full suite, then grep for the Laravel 8 idioms Laravel 9 removed — $dates on models, str_*/array_* helpers that moved to Illuminate\Support\Str, and any doctrine/dbal-dependent column changes. A package major that tracks a framework major often drags these along with it.

Wrap third-party calls behind your own thin service. The package is an implementation detail; your application code should call App\Services\Thing, which delegates to the package. When v5 lands, one file changes instead of thirty.

Use the package's test doubles in feature tests and the real thing in integration tests. Fakes keep the suite fast and deterministic; a small integration suite (often tagged and excluded from the default run) catches the wiring mistakes fakes hide — misconfigured credentials, wrong queue connection, missing migration.

For queued work, make handlers idempotent. Anything dispatched through the package can be retried; guard against duplicate side effects with an idempotency key or an existence check rather than assuming single delivery.

Gotchas and Tips

• "Laravel 9 support added" on a major version is a warning, not a changelog. Read the actual diff for v3 → v4. Removed methods, renamed config keys, and dropped PHP 7.x support all typically ride along in a major bump and won't appear in a one-line release note.
• Constraint conflicts are usually transitive. When composer require fails, composer why-not vendor/package 4.0 names the package holding you back — often a dev dependency (PHPUnit bridge, static analysis tooling, an old Laravel Debugbar) rather than a runtime one.
• PHP 8.0 is a hard floor. Your CI image, Docker base image, and any local tooling need bumping first, or the upgrade stalls on infrastructure rather than code.
• Stale config after publishing. Run php artisan config:clear (and cache:clear if the package registers routes or views) after publishing or editing the config file — an old cached config is the most common "the package is broken" false alarm.
• Publish tags, not the whole provider, where possible. vendor:publish --tag=... avoids overwriting files you've already customised. Never publish and commit a config file whose only difference from the default is comments.
• Long-running processes hold state. Under Octane or a queue worker, the package's singleton bindings persist across requests/jobs. If the package caches per-request data, reset it in a middleware or job-level hook.
• Debug with the container, not with dd(). php artisan about, php artisan tinker + app()->bound(Contract::class), and the provider's register()/boot() split will tell you far more about why a binding isn't resolving than dumping a facade call.
• Extension points to prefer: the published config, the interfaces the provider binds, and framework events the package dispatches. Prefer these over subclassing the package's concrete classes — subclasses break on every major version, and v5 will find you.
• Watch the deprecation log, not just the test results. Laravel 9's deprecation notices (and PHP 8.1's) surface in storage/logs/laravel.log during the test run; a green suite with a noisy log is a v5 upgrade that's already overdue.