Eloquence Laravel Package

Getting Started

• Confirm compatibility first. 9.0.0 is a major bump whose headline change is Laravel 9 support. Before installing, verify the package's composer.json constraints (illuminate/*: ^9.0, PHP ^8.0) against your app. On Laravel 9 you are also on Symfony 6 and PHP 8, so any transitive dependency pinned to older versions will surface here rather than at runtime.
• Install and inspect the manifest. Run composer require vendor/package:^9.0, then open the package's composer.json and README to see what the service provider registers. The extra.laravel.providers / aliases block tells you whether discovery is automatic or you must register manually in config/app.php.
• Publish configuration before writing code. php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider" (add --tag=config if tags are defined). Read the published config/{package}.php top to bottom — it is the fastest map of the package's capabilities and defaults.
• First use case. Wire the package into a single, low-risk entry point: a controller action or an artisan command. Resolve the package's main class from the container (app(Vendor\Package\Client::class) or the facade) and confirm a round trip works before integrating it into jobs, listeners, or middleware.
• Where to look first when something is unclear. In order: the package's README, the published config file, the service provider (what it binds and singleton-registers), then the tests directory if shipped. The provider is the authoritative answer to "how is this instantiated and with what dependencies."

Implementation Patterns

• Prefer container resolution over new. Register the package's client/manager as a singleton in a small app-level service provider if it is not already bound that way. This keeps configuration injection consistent and makes it swappable in tests.
• Wrap third-party calls in your own thin adapter. Define an interface in your app (App\Contracts\FooGateway) and an implementation that delegates to the package. Controllers, jobs, and listeners depend on the interface. This is the single highest-leverage pattern for third-party packages: it isolates you from the package's API surface, makes fakes trivial, and turns a future major upgrade into a one-file change.
• Configuration via environment, not code. Map package config values to env() in the published config file and set them per environment in .env. Never edit the published config with hard-coded credentials; treat it as a template.
• Feature-flag the integration. Gate the code path with a config boolean (config('foo.enabled')) so you can disable the package in local/CI without removing code, and so a failing dependency degrades gracefully in production.
• Queue anything that crosses a network boundary. If the package makes HTTP calls or writes to an external system, call it from a job with $tries, $backoff, and failed() handling. Do not call it inline in a request lifecycle.
• Testing pattern. In TestCase, $this->app->instance(FooGateway::class, new FakeFooGateway()) and assert against your interface. For integration tests, use RefreshDatabase and the package's own fakes if provided. Keep at least one test that exercises the real config resolution so a bad publish or env key is caught.
• Observability. Log around the adapter with a correlation ID, and emit a metric or log line on failure. The package will not know your request context; your adapter should.
• Upgrade hygiene. Because 9.0.0 is a major release, pin ^9.0, read the package's changelog/upgrade notes for anything beyond the Laravel 9 line item, and run your adapter's test suite as the gate — not the package's.

Gotchas and Tips

• A major version for a compatibility bump is still a major version. "Support for Laravel 9 #1" suggests the release exists primarily to widen framework constraints. That often means a dropped PHP version floor and possibly dropped support for Laravel 8. Check composer.json for an illuminate/support floor; if it is ^9.0 only, you cannot run this on Laravel 8 apps and a monorepo with mixed versions will conflict.
• PHP 8 is implied. Laravel 9 requires PHP 8.0+. If your CI matrix or a shared base image still runs 7.4, the install will fail before any code runs. Update the matrix as part of the upgrade.
• Symfony 6 fallout. Laravel 9 moved to Symfony 6 components. Any package that type-hints against Symfony 5 interfaces will break. If you see Declaration of ... must be compatible with ... errors, the culprit is usually a transitive dependency, not this package.
• doctrine/dbal behavior changes. If the package touches schema introspection or column modification, Laravel 9's dbal 3 upgrade changes return types (e.g. Doctrine\DBAL\Types\Type registry). Verify migrations and any package commands that inspect the schema.
• String and helper deprecations. Laravel 9 deprecates str_* / array_* global helpers in favor of Str:: / Arr::. If the package or your adapter uses them, expect deprecation noise in logs; silence it deliberately rather than by lowering the error level.
• Anonymous migrations. New Laravel 9 migrations are class-less by default. If the package publishes migrations, check they are compatible with your migration naming and that migrate:fresh in CI does not collide with existing class names.
• Config and route caching. After publishing config or registering the provider, run php artisan config:clear (and route:clear if routes are registered). Stale cached config is the most common cause of "the package ignores my .env."
• Discovery cache. If you added the provider manually while also having it in extra.laravel.providers, you will get double registration. Pick one; run php artisan package:discover after changing dependencies.
• Debugging entry point. When a call fails, first check storage/logs/laravel.log for the bound class name, then php artisan tinker and app()->make(...) to confirm the container resolves it with the config you expect. dd(config('package')) inside a route is faster than reading source.
• Extension points. The provider's register()/boot() and its published config are the intended extension seams. If you need behavior the package does not expose, decorate the bound class and re-bind in your own provider rather than forking — forking a package that is mid-major-version will cost you on the next bump.
• Lockfile discipline. Commit composer.lock for applications. A ^9.0 constraint on a freshly-released major means patch releases may land quickly; a lockfile keeps CI deterministic while you evaluate them.