Guzzle Bundle Laravel Package

Product Decisions This Supports

Build vs. buy vs. framework-native (integration layer). The bundle is a configuration layer over Guzzle, not a new HTTP client. Adopting it is a decision not to build an in-house "API client registry" (base URLs, auth, timeouts, headers, retries, logging) — that glue is the recurring cost most platform teams quietly rebuild. The buy option is cheap (MIT, no license spend), and the "framework-native" alternative (Symfony's own symfony/http-client) is the genuine competing option you should decide against explicitly in an ADR.

Vendor-integration roadmap and time-to-market. Because every client is declared in config/packages/eight_points_guzzle.yaml (base_url, auth, headers, curl options, timeout, lazy loading), adding a new third-party provider (payments, CRM, tax, shipping, KYC) becomes config plus a thin service rather than an architecture project. This lets you commit roadmap dates for "support provider N" with far less engineering variance, and it makes per-environment differences (sandbox vs. production base URLs, credentials via env vars) a deployment concern instead of a code branch.

Reliability and service-level policy. slow_response_time (ms threshold) plus per-client timeout and the supported retry plugin let you turn "third-party APIs are flaky" into an explicit, reviewable policy: which integrations retry, how many times, what counts as slow, and where the error budget sits. This is the material you need to negotiate SLAs or justify circuit-breaker work.

Observability and supportability features. Logging into Symfony's default logger with a known format (eight_points_guzzle.{level}: {method} {uri} {code}), the debug toolbar/profiler panel, and the pre_transaction / post_transaction events (generic and per-client) give you a cheap way to deliver audit trails, PII scrubbing, correlation-ID propagation, and cache-control headers as cross-cutting listeners instead of copy-pasted code. Client-specific listeners overriding generic ones is a useful governance property: platform defaults, team overrides.

Security and compliance decisions. Centralizing auth, headers, and curl sslversion in one reviewed config file is a control, not just convenience — it makes "no hardcoded credentials," TLS version pinning, and header hygiene auditable in one place rather than across N service classes.

Platform lifecycle / upgrade decisions. Recent releases show active Symfony-version tracking (Symfony 5–8, including SF8 support in v8.6.0 and PHP 8.4 deprecation fixes), so this does not block a Symfony major upgrade. Low lock-in: configured services are plain Guzzle clients (eight_points_guzzle.client.<name>), so an exit is a DI alias change — which is exactly why the README's "create aliases" suggestion is worth enforcing as a team standard.

Use cases that fit: a Symfony monolith or modular monolith with 3–15 outbound HTTP integrations; multi-tenant SaaS with per-tenant credentials; internal platform teams standardizing how product squads call external APIs; environments where developers need request-level visibility without a paid APM.

Use cases that do not fit: Laravel applications (see below), single-integration products, or anything needing streaming, HTTP/2 multiplexing, or high concurrency.

When to Consider This Package

Adopt when all of the following hold:

• The application is Symfony 5.x–8.x on PHP 7.2+. Be blunt internally: despite being filed under "Laravel/PHP," this is a Symfony-only bundle. In Laravel, use the built-in Illuminate\Support\Facades\Http client (which wraps Guzzle) — there is no product reason to install this there.
• You have more than two or three external HTTP integrations, or you expect to. Below that, a plain Guzzle client or symfony/http-client is simpler and the config indirection is pure overhead (YAGNI).
• You want integration concerns — credentials, base URLs, timeouts, retries, logging, request/response interception — governed centrally and reviewable by someone who isn't the original author.
• Your team already writes Guzzle, or you need a specific Guzzle plugin (OAuth2, WSSE, cache, header-forwarding, retry). The plugin registry is the bundle's main differentiator versus symfony/http-client.
• Developer observability matters: the profiler panel is a real onboarding and debugging accelerator for squads new to an integration.

Look elsewhere — or decide against adopting — when:

• Laravel or framework-agnostic code: use Laravel's HTTP client, or Guzzle directly with a small factory.
• You want the framework-native path. symfony/http-client is the Symfony-blessed HTTP abstraction, supports PSR-18, async/streaming, and needs no bundle glue. If your org policy favors fewer third-party bundles, that's a legitimate and probably stronger default; the counter-argument is Guzzle's plugin ecosystem and your team's existing familiarity.
• You consume a vendor SDK with its own client (payments, LLM providers, email). Wrapping an SDK in this bundle adds a layer that will fight the SDK's own retry/auth model.
• You need high concurrency, streaming, or HTTP/2 workloads — evaluate on a spike, don't assume.
• Bus-factor or maintenance risk is unacceptable. Releases are current, but this is a small, effectively single-maintainer community bundle. The reported dependent count is not a meaningful adoption signal; check commit cadence and open-issue responsiveness yourself, and require an internal owner. Have an exit plan: aliases + plain Guzzle clients make replacement a contained change.
• Compliance regimes requiring vetted, supported dependencies — treat this as a risk-register entry, not a blocker.

Recommended decision process: timebox a one-sprint spike that ports two existing integrations, one authenticated and one with retries, and measures (a) lines of glue code removed, (b) profiler/log usefulness in a real incident drill, (c) behaviour under timeout and 5xx. Then write the ADR choosing between this bundle, symfony/http-client, and raw Guzzle.

How to Pitch It (Stakeholders)

For executives (one paragraph). We spend recurring engineering time rebuilding the same plumbing every time we connect to a third-party API — credentials, timeouts, retries, logging, audit trails — and every rebuild is a place where security and reliability standards drift. This package is a free, MIT-licensed, actively maintained Symfony component that replaces that plumbing with reviewed configuration: integrations are declared in one file, requests and responses are observable and interceptable, and each vendor gets consistent timeout and retry behaviour. The business outcome is faster, cheaper onboarding of new providers, fewer production incidents caused by third-party flakiness, and a cleaner audit story for credentials and TLS settings. It is a low-cost, low-lock-in decision — clients remain standard Guzzle clients, so we can back out with a configuration change — but it is Symfony-only, so it does not apply to our Laravel services, and it carries a small-project maintenance risk that we mitigate by assigning an internal owner and keeping an exit path. Ask: approve a one-sprint evaluation spike, not a permanent commitment.

For engineering leads (summary).

• What it is: a Symfony bundle that registers configured Guzzle clients (eight_points_guzzle.client.<name>) in the DI container, with a Flex recipe, autowiring support, and a documented config reference.
• What we stop writing: per-integration base URL, auth, headers, curl/TLS options, timeout, and lazy-loading boilerplate.
• What we gain: a profiler panel and standardized logging (plus slow_response_time thresholds) for free; generic and per-client pre_transaction/post_transaction events as the sanctioned place for correlation IDs, audit logging, PII scrubbing, and header policy — no more bespoke middleware per integration.
• Extensibility: a plugin registry with maintained OAuth2, WSSE, cache, header-forward, and retry plugins; a documented path for single-file in-house plugins.
• Constraints to design around: Symfony 5–8 / PHP 7.2+ only; small maintainer base — we own the integration layer, not the package; we must enforce service aliases (crm.client: '@eight_points_guzzle.client.crm') so a future swap to symfony/http-client is a one-line change per consumer.
• Definition of done for the spike: two real integrations ported, retry/timeout policy documented and tested against a failing endpoint, logging/audit listener in place, and an ADR comparing this bundle against symfony/http-client. Success metrics: integration lead time per new provider, share of outbound calls with enforced timeout/retry, and count of third-party incidents traced via profiler/logs.