Http Client Laravel Package

Product Decisions This Supports

Feature & integration work

• Third-party API integrations — the package is a PSR-18 HTTP client with a pluggable transport adapter (cURL, stream, HAR replay). Any roadmap item that means "talk to Stripe/SendGrid/Shopify/an internal service" needs exactly this layer, so it can standardise on one outbound HTTP client instead of each squad hand-rolling curl_exec.
• Stateful partner integrations — the Session component (persistent cookies + request history) unlocks multi-step auth flows, legacy portal automation, and SSO handshakes that stateless clients make painful.
• Reliability features shipped, not built — method-aware redirect handling (307/308 preserve method and body) and retry-with-backoff are already implemented. That is directly a product-safe behaviour: fewer duplicated POSTs, fewer "why did the payment go through twice?" incidents.
• Webhook delivery and callback fan-out — retry/backoff logic is the same primitive you need for outbound event delivery; you can validate the pattern on a low-risk integration before investing in a dedicated delivery service.

Testing & QA roadmap

• HAR replay adapter is the standout product capability. It lets you record real production traffic against an external API and replay it deterministically in CI. That converts "we can't test this integration without sandbox credentials and a flaky third party" into an offline, reproducible test suite. This is a roadmap-level win for integration confidence.
• Reduces the need for a mock-server vendor (WireMock, MockServer, VCR-like SaaS) for PHP services — a build-vs-buy saving.

Build vs buy

• This is a buy/adopt, not build. Writing a correct PSR-18 client (redirects, retries, streaming bodies, cookie jars) is 2–4 weeks of engineering plus ongoing correctness debt for something that is not your differentiator. Adopting is close to free under MIT.
• Lock-in exposure is unusually low. The client implements PSR-18, so ClientInterface is the seam. You can swap in Symfony HttpClient or Guzzle later by changing a container binding, not application code. That makes this a reversible decision — which is what lets you say yes.
• Framework coupling is optional. Although distributed inside the Berlioz monorepo, the HTTP client is listed as a standalone component alongside Mailer, Form, and HtmlSelector. You do not have to adopt the Berlioz kernel/DI/router to use it.

Roadmap sequencing

• Adopt as an internal standard for outbound HTTP behind our own thin interface, not sprinkled through domain code. Then evaluate whether the retry/backoff policy belongs in a shared resilience layer (circuit breakers, timeouts, per-host budgets) — the package gives you the transport; it does not give you a service-mesh-grade resilience policy.
• Do not put this on the roadmap as a synchronous client for high-fan-out, high-concurrency workloads. PSR-18 is request/response and blocking by design; if the roadmap includes bulk enrichment against an API with hundreds of concurrent calls, plan for a queue/worker architecture (the sibling berlioz/queue-manager in the same monorepo is the natural pairing) rather than expecting concurrency from the client.

When to Consider This Package

Adopt when:

• Your stack is PHP 8.2+ and you want a strict, modern, PSR-12 codebase (the project enforces declare(strict_types=1), PSR-4/7/11/12/14/16/17/18 across the monorepo).
• You already value PSR compliance as an architectural constraint — the payoff is that this decision is cheap to reverse.
• You need HAR-based replay testing for third-party integrations and don't want to stand up mock infrastructure.
• You need cookie-session semantics (stateful flows) which many lightweight clients omit.
• You are already in, or evaluating, the Berlioz ecosystem and want the components to compose (Twig, Hector ORM, QueueManager, FlashBag, Form, HtmlSelector, Mailer all ship in the same monorepo with the same conventions).
• You want a small dependency surface and are comfortable pinning a version and reviewing changelogs on upgrade.

Look elsewhere when:

• You need the ecosystem, not just the client. One GitHub star, zero dependents, and a single-maintainer history mean no Stack Overflow corpus, no third-party extensions, no recruiting pool, and a real bus-factor-of-one. If your org's risk model forbids single-maintainer dependencies in the critical path, this is disqualifying — regardless of code quality.
• You need concurrency or streaming-scale throughput. PSR-18 is synchronous. Symfony HttpClient (with its async/HttpClientInterface extensions) or an async runtime is the right answer.
• You need production-grade observability and resilience out of the box — distributed tracing hooks, OpenTelemetry spans, connection pooling, circuit breakers, per-host rate limiting, HTTP/2 multiplexing, proxy/mTLS enterprise config. You would be building these on top.
• You need commercial support, an SLA, or a security-response commitment for a regulated workload (PCI-adjacent payment flows, healthcare). MIT with no vendor behind it means you own the CVE response.
• Your team is Laravel/Symfony-native. Laravel ships Illuminate\Support\Facades\Http (Guzzle-backed); Symfony ships its own client. Adding a third HTTP abstraction to a team fluent in those is negative value — the maintenance savings don't materialise.
• You need a mock/test double story that's HTTP-client-agnostic. If QA is standardising across languages, a language-neutral mock server beats a PHP-only replay adapter.

Conditional middle ground: adopt it as the transport behind your own HttpClient port/adapter interface, with a one-line swap path to Guzzle. That captures the retry, redirect, cookie, and HAR-replay value while neutralising the bus-factor and ecosystem risk. This is the recommended posture.

How to Pitch It (Stakeholders)

For executives — one paragraph: We can adopt a small, MIT-licensed, standards-compliant PHP HTTP client instead of building and maintaining our own outbound-request layer. It is free, it implements the industry PSR-18 standard so we are not locked in — we can replace it with a commercially supported alternative by changing a single configuration binding — and it already includes the reliability behaviours we would otherwise spec and build: safe redirect handling that doesn't corrupt request bodies, and automatic retry with backoff. The strategic ask is small (adopt behind an internal interface, no vendor contract, no licence cost). The honest risk is that it is maintained by a single author with a very small community, so we treat it as an interchangeable component rather than a platform commitment and keep a swap path tested.

For engineering leadership:

• Correctness we don't have to write: method-aware 307/308 redirects (body re-sent correctly) and retry-with-backoff are the two places hand-rolled HTTP clients most often cause production incidents. Here they're implemented and tested.
• Transport is an adapter: cURL, PHP streams, or HAR replay behind the same interface. That means we can unit-test integration code with zero network and zero third-party sandbox dependency — a direct reduction in flaky CI.
• PSR-18 ClientInterface boundary: we inject the interface, not the concrete client. Swapping to Guzzle or Symfony HttpClient is a container binding change, so the dependency is a low-regret, reversible decision.
• Codebase hygiene: PHP 8.2+, declare(strict_types=1) everywhere, PSR-12, conventional commits, PHPUnit across 17 suites, Rector for automated refactoring. Reviewing a diff here is cheap.
• Conventions we should copy regardless of adoption: the monorepo's package lifecycle (config() → register() → boot()), PSR-14 event dispatching for cross-cutting concerns, and the auto-wiring/inflector container pattern are good reference designs for our own service layer.
• Mitigations to agree before merge: pin the exact version in composer.json, add it to the dependency-review/SCA watchlist, add an integration test that exercises the client through our port so a swap is provably safe, and record a named owner for upgrade and CVE triage.

For the adopting team — the one-liner: Take the transport, not the framework: bind Psr\Http\Client\ClientInterface to this client, wrap it in our own outbound-HTTP port, use the HAR adapter in CI, and keep the swap to Guzzle a one-line change.