Larafeed Laravel Package

Getting Started

• Install with composer require vendor/package:^3.0. Version 3.0.0 is the first line that declares Laravel 9/10 support — if you are still on Laravel 8, stay pinned to the 2.x line. When resolution stalls, read the solver error literally and run composer why-not vendor/package 3.0.0; the usual culprits are a PHP platform constraint (php -v, need 8.0+ for Laravel 9 and 8.1+ for Laravel 10) or another dependency pinning illuminate/*.
• On Laravel 9/10 the service provider and facade are auto-discovered. You should not need to touch config/app.php. If you have disabled discovery or you are registering the package from inside another package, add the provider manually and confirm it with bootstrap/cache/packages.php.
• First place to look after install is the published config: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag=config. The config keys map closely onto the constructor arguments of the underlying client, so the config file is effectively the package's public API surface. Read it before reading the source.
• Verify the wiring before writing any feature code. Resolve the facade or contract out of the container (php artisan tinker → app('package.manager') or the facade root), or use php artisan about on Laravel 9+. If that throws, the problem is a binding or config issue, not your calling code.
• First real use case: take the default config, point it at one resource/connection, and exercise a single end-to-end call through the facade in Tinker or a throwaway artisan command. Get one round trip working before adding queues, caching, or multiple connections — otherwise you cannot tell which layer is failing.

Implementation Patterns

• Resolve through the container, never new. Type-hint the package's contract or facade in controllers, jobs, and commands. This is what makes $this->mock(...) / $this->instance(...) work in tests, and the only way the package's config and customized HTTP client actually apply.
• Config-first, env-backed. Keep credentials, endpoints, and timeouts in config/package.php sourced from .env. Never hardcode them at call sites; the package reads config at construction time and will not see values you set later on an already-resolved singleton.
• Put a thin service between your domain and the package. An App\Services\... wrapper gives you one place for retries, logging, and DTO mapping, and it means a future major version bump touches one file instead of twenty call sites.
• Queue anything that leaves the process. Remote API calls, exports, and syncs belong in jobs with $tries, $backoff, and a failed() handler. Distinguish retryable transport errors from permanent auth/validation errors using the package's exception classes rather than string-matching messages.
• Multi-tenant / multi-connection setups. Where the package supports named connections, register them via config()->set() before first resolution, or use the package's own connection manager. Mutating config after a singleton is resolved has no effect — this is the most common multi-tenant bug with packages of this shape.
• Testing. Use Http::fake() and Bus::fake(), and enable Http::preventStrayRequests() so an unmocked call fails loudly instead of hitting the network in CI. Bind a fake implementation through the container in setUp(); prefer that over hitting a sandbox.
• Extend via events and contracts, not subclasses. Listen to the package's events or implement its interfaces. Those are the surfaces that survive minor upgrades; internal classes are not.

Gotchas and Tips

• 3.0.0 is a compatibility declaration, not a feature release. The release note is one line — "Support Laravel 9/10." Treat the upgrade as a dependency-resolution exercise, and confirm there is no breaking surface by diffing CHANGELOG.md and the published config against your copy.
• Compare configs on a scratch branch. Run php artisan vendor:publish --force on a throwaway branch and git diff the config file. Any keys added in 3.0.0 default to whatever the package chose, which may not match your 2.x runtime behavior even though nothing "broke."
• Config caching hides env edits. For any "I changed it and nothing happened," clear in this order: php artisan optimize:clear (config, routes, views), then check opcache. A stale bootstrap/cache/config.php is the single most common local-vs-CI discrepancy.
• Auto-discovery fails silently with a typo'd provider class. You get an obscure binding error deep in the stack rather than an obvious one. Inspect bootstrap/cache/packages.php to see what Laravel actually registered.
• Upgrading 8 → 10 directly is a bad idea. Do your own framework deprecation cleanup first, so the package's notices are distinguishable from yours. Laravel 10 removed several idioms that will generate noise from your application code, not the package.
• Extension points to prefer: published config, container bindings, events, and the package's published contracts. Avoid editing vendor/ and avoid extending anything marked @internal — both are exactly where the next major version will break you.
• Debugging shortcut: resolve the manager in Tinker and inspect it. If the config looks correct on the resolved instance but calls still fail, the problem is upstream — credentials, network, or the remote service — and not the package.