Guzzle Bundle Laravel Package

Getting Started

• Reality check first: this is a Symfony bundle. Laravel has no bundle loader, no bundles.php, no auto-discovery. There is no service provider, no facade, no publishable config in the package. Nothing here runs unmodified in a Laravel app.
• Ten-minute evaluation, in this order:
  1. composer.json — read require for guzzlehttp/guzzle and symfony/* ranges plus require.php. If Guzzle is pinned to ^5.0 or ^6.0, Composer will refuse to install alongside Laravel's own guzzlehttp/guzzle: ^7.x dependency. This is usually the end of the exercise.
  2. src/DependencyInjection/Configuration.php — this file is the package's real value: a config tree describing named clients, base URIs, timeouts, and handlers/middleware.
  3. src/DependencyInjection/*Extension.php — shows how each configured client becomes a service definition.
  4. Commit date and open issues. Zero stars, zero dependents, score 0 means assume unmaintained until proven otherwise.
• First use case if you proceed: don't install it. Copy the pattern — a config/guzzle.php array of named clients and a small factory that builds GuzzleHttp\Client instances from it, bound as singletons by name.
• If you truly want to read the bundle's runtime behavior, install it in a scratch Symfony app, not in your Laravel composer.json.

Implementation Patterns

• Named client registry. One config entry per upstream (payments, crm, shipping) with base_uri, timeout, headers, retry. Resolve clients by name from the container instead of injecting five distinctly-named clients into constructors.
• Service provider shape:
  • register() — merge config/guzzle.php, bind a GuzzleClientFactory singleton.
  • boot() — nothing. Never resolve clients at boot; that turns HTTP config into a boot-time dependency for every request and every artisan command.
• Lazy construction. Bind each named client as a singleton closure that builds on first resolution. Keeps handler stacks and middleware out of workers that never make HTTP calls.
• Middleware as the extension point (this is what the bundle's handler config is doing):
  • Logging via a LoggerInterface-injecting middleware, scoped to a dedicated channel.
  • Retries via RetryMiddleware with an explicit decision function — don't hand-roll sleep() loops in services.
  • Correlation ID injection in mapRequest so logs line up across services.
• One HandlerStack per named client so a noisy API can run verbose logging while another stays silent.
• Type-hint an app interface, not Guzzle. PaymentGateway taking a ClientInterface lets you swap to Laravel's Http facade later without touching call sites.
• Testing: build a client with HandlerStack::create(new MockHandler([...])), or rebind the container entry in setUp(). Assert against the mock's last request.
• Queues: pass the client name into job constructors, not the client. Middleware containing closures is not serializable and will break job dispatch.
• When to skip Guzzle entirely: for plain JSON calls, Http::baseUrl(...)->retry(...)->withToken(...) covers it with far less wiring. Reserve a Guzzle registry for streaming, custom handler stacks, non-standard auth, or PSR-18 interop.

Gotchas and Tips

• Bundle ≠ Composer package for Laravel. Any README mentioning AppKernel, services.yml, config.yml, or @GuzzleBundle is Symfony-only. Translating YAML service definitions into a Laravel provider is the entire job — for a package with no maintainer.
• Version conflicts are the first failure, not the last. Run composer why-not xigen.io/guzzle-bundle before debugging anything else. A forced Guzzle downgrade breaks Laravel internals in confusing ways.
• No facade, no config: publish, no extra.laravel. You wire every piece by hand; budget accordingly.
• Abandonment risk is the headline. Zero dependents and no review trail means any copied code is yours to maintain. Pin exact versions and prefer code you can rewrite in thirty lines.
• http_errors semantics. Default true throws RequestException on 4xx/5xx. If downstream code inspects status codes, set http_errors => false per client — and check whether the bundle's config tree exposes that at all. If it doesn't, you're building clients by hand anyway.
• base_uri trailing slash. https://api.example.com/v1 + /users resolves to https://api.example.com/users — the /v1 silently disappears. End every base_uri with / and be consistent about leading slashes in paths.
• Infinite timeouts. Guzzle's default timeout is 0. A config-driven client that omits it will hang queue workers forever. Set both timeout and connect_timeout on every entry.
• debug => true dumps bodies — including credentials — to stdout. Use only transiently, never committed, and prefer a scoped logger middleware.
• PSR-18 vs Guzzle client. Guzzle 7 implements PSR-18/17; older versions don't. Typing against PSR-18's ClientInterface gains swappability but loses Guzzle-only options (handler, sink, progress). Decide per call site.
• Extension points worth preserving if you copy the pattern: global middleware registration, per-client middleware, per-client HandlerStack override. Those three cover nearly all real customization.
• Config caching. config:cache serializes to arrays — keep client definitions array-only (no closures or objects) so the registry still builds after caching.
• Recommendation: for day-to-day Laravel work use Illuminate\Support\Facades\Http. Reach for raw Guzzle only for streaming, custom stacks, or PSR-18 interop. Reach for this bundle only if it's already in a legacy codebase and you're planning its removal.