Http Client Laravel Package

Technical Evaluation

What is actually being evaluated. berlioz/http-client is one package inside the Berlioz Framework monorepo (src/Http/Client/). It is a PSR-18 HTTP client with a transport-adapter pattern (cURL, PHP stream, HAR replay), a stateful Session for cookies and request history, method-aware redirect following (307/308 preserve method and body), and retry with backoff. PHP >= 8.2, MIT, PSR-4/7/11/12/14/16/17/18 compliant. The published metadata (1 star, 0 dependents, score 20.68, opportunity 37.56, "last release 2026-10-24") describes a package with essentially no external adoption and a release timestamp that is inconsistent with the current date — a metadata-credibility flag we must resolve before relying on any version pin.

Architecture fit. The single most important fact for a TPM is that the integration contract is PSR-18, not Berlioz. That decouples the decision from the framework: we can consume this client without adopting berlioz/core, the DI container, the router, or the HTTP kernel. Conversely, it means the value we would be buying is not the transport (a commodity) but the extras — Session, retry/backoff, method-aware redirects, HAR replay. Those extras are also, conveniently, the parts that are not covered by any PSR, so they are the parts that create lock-in. Frame the architecture decision as: "commodity PSR-18 transport behind our own seam, with a small, isolated set of Berlioz-specific behaviours we are willing to own if the package is abandoned."

The PSR alignment itself is architecturally clean: message objects come from a PSR-17 factory (either berlioz/http-message's HttpFactory or our existing implementation), so we are not forced into Berlioz's message layer. The adapter abstraction is the right shape for testability and for swapping transports.

Integration feasibility. High for a pilot, moderate for production. The API surface is small and standard (sendRequest()); a spike should take under a day. Feasibility risk concentrates in three places:

Technical risk.

• Bus factor = 1. Single named maintainer, monorepo-internal release tooling, no visible vendor or foundation backing. This is the dominant risk, not code quality.
• Adoption risk is a proxy for support risk. 1 star / 0 dependents means near-zero field hardening: edge cases in redirect bodies, chunked transfer, TLS defaults, and cookie domain matching will be encountered by us first.
• HAR replay is a production foot-gun. A config-driven adapter that can replay canned responses is excellent for CI and dangerous if misconfigured in a deployed environment. Needs a hard guard (env-gated construction, fail-closed).
• Stateful Session in long-lived workers. Cookies and history held in an object are fine per-request, hazardous under Octane/RoadRunner/Swoole where the container persists across requests — cross-tenant cookie leakage is a plausible, high-severity failure mode.
• Release metadata anomaly. A future-dated "last release" undermines the score inputs; verify tags, CI status, and changelog before treating the project as actively maintained.

Key questions for the maintainer/vendor.

1. Is berlioz/http-client versioned and released independently of the monorepo, and what is the support window per major?
2. What is the CI matrix (PHP 8.2–8.5?), coverage per package, and is there a security disclosure process?
3. Which adapters are production-grade vs. test-only (cURL, stream, HAR)? Are proxy, mTLS, and custom CA bundles supported?
4. Default timeouts, connect timeouts, and max-redirects — are safe defaults set, or must every consumer opt in?
5. Retry semantics: which status codes/verbs are retried, is idempotency required, and is jitter applied?
6. Is Session scoped per request or per client instance, and is there a documented reset for worker runtimes?
7. Is there any concurrency story (curl_multi, pool, Fibers) or an explicit "not supported" statement?
8. How do we instrument PSR-18 traffic without forking — are there hooks, or must all instrumentation live in our decorator?

Integration Approach

Stack fit. Good where the stack is PHP 8.2+, PSR-7/17/18-aware, and either already framework-agnostic or already Berlioz. It fits as a library, not as a platform decision. If our application is Laravel/Symfony, we would be introducing a second HTTP client alongside the framework's native one — acceptable only if justified by a specific capability (HAR replay in tests, uniform adapter swapping) and only behind an interface so that the duplication is reversible. If we are already on Berlioz, fit is native: the client participates in the container, config, and event layers with no glue code.

Migration path. Adopt in three bounded steps:

1. Seam first, library second. Define our own narrow port — e.g. HttpTransport::send(Request): Response — or depend directly on Psr\Http\Client\ClientInterface and inject. No application code should ever name a Berlioz\... class outside the adapter module. This is the whole mitigation: it makes the vendor decision a one-file swap.
2. Land it on non-critical paths. Outbound webhook dispatch, third-party integration clients without SLA, and test doubles via HAR replay (highest value, lowest risk — HAR replay alone can justify a trial).
3. Promote path-by-path to user-facing critical paths only after contract tests, chaos drills (timeouts, 5xx storms), and a documented fallback to the incumbent client.

Compatibility. Verify: PSR-17 factory injection works with our existing message implementation (do not drag in http-message if we already have one); no hard dependency on berlioz/service-container when used standalone; conflict-free with whatever psr/http-client implementation we already ship (composer replace/provide collisions are a real risk in a mixed stack); PHP minor-version support aligned to our runtime; and behaviour of Session under our SAPI (FPM vs. worker).

Sequencing. (a) Metadata audit — tags, CI, changelog, adapter maturity — before any code; (b) 1-day spike behind the seam with HAR replay in tests; (c) contract-test suite written against PSR-18 so it runs unchanged against the incumbent and against Berlioz; (d) shadow mode on one low-risk integration; (e) go/no-go gate on maintainer responsiveness and a fork-and-maintain cost estimate.

Operational Impact

Maintenance. Assume we may own this code. A single-maintainer, low-adoption package is a reasonable dependency only when the exit cost is near zero — which PSR-18 makes true for transport and false for Session/retry/redirect behaviour. Budget: ~0.1 FTE ongoing for version tracking and adapter fixes, plus a one-off ~2–3 days to reach the point where a fork is a viable option (vendoring, CI, release). Treat the fork as a pre-planned contingency, not a failure mode.

Support. Community-only, best-effort, no SLA. Internal escalation must therefore route through our own HTTP-platform owner. Because issues live centrally in the monorepo, triage expectations should be set low; do not plan a roadmap dependency (e.g. "wait for upstream HTTP/2 support") around this project.

Scaling. Per-process synchronous client; connection reuse depends on adapter handle reuse — confirm that cURL handles are pooled or at least kept alive per client instance, otherwise expect TLS handshake overhead per call. Memory is dominated by PSR-7 message bodies; large downloads must stream, so verify the client does not buffer whole bodies. Throughput scaling is a function of worker count, not of this package. If a product requirement emerges for parallel fan-out, plan for a separate concurrency layer rather than expecting it here.

Failure modes to design against.

Ramp-up. Low for consumers — sendRequest() is one method and PSR-18 is well understood; a mid-level engineer is productive in under a day. Higher for operators and on-call: debugging retry/redirect/cookie behaviour requires reading package source, because documentation depth in a 1-star monorepo package is not a safe assumption. Plan one engineer to become the designated owner (read the adapter and Session code end-to-end), document the failure matrix above in the runbook, and add the contract-test suite to CI so upgrades fail loudly rather than in production.

Recommendation. Conditional adopt, scoped to the PSR-18 seam. Approve for test infrastructure (HAR replay) and non-critical integration clients now; gate production critical-path adoption on (i) resolving the release-metadata anomaly, (ii) evidence of adapter maturity and timeout/retry defaults, (iii) a written fork-and-maintain cost, and (iv) all traffic flowing through our own interface so the incumbent client remains a one-line fallback. Do not adopt Berlioz core, container, or router as a consequence of this package.