Guzzle Laravel Package

Product Decisions This Supports

• The value story is now decoupled from the libcurl gate (the big change since 8.2.0): 8.2.0's headline — connection caps plus persistent transport sharing — was inert below libcurl 8.22.0, which made the whole upgrade a base-image-refresh decision. 8.3.0 ships runtime-independent value: a hardened stream handler and a typed transfer-failure error path. This lets you re-sequence the roadmap: bank the 8.3.0 hardening first as a contained, measurable release, and keep the libcurl cap+share work as a separately funded initiative.
• Stream handlers are now a product-grade transport, not a convenience: bodies end at their declared Content-Length (including 0), chunked bodies decode as they arrive and must terminate at the last chunk, truncated/malformed chunked bodies are rejected, unsupported transfer codings are rejected, and gzip/deflate trailing-data rules match libcurl. This turns silent truncation into deterministic exceptions — a data-integrity decision for reporting, exports, invoices, webhooks, and ETL pulls. It also fixes bytes being delayed when they arrive with the headers, which affects time-to-first-byte on streamed responses.
• A new error taxonomy is an observability/retry-policy decision: cURL errors 8 and 23 with a response are now classified as ResponseTransferException. That's the hook for retry/alerting policy that distinguishes "transfer died mid-body" from generic connection failure — but only if you update error handling and dashboards. Silence here creates a blind spot, not a crash.
• The dependency floor rises — this is a vendor/ecosystem decision: guzzlehttp/promises ^3.1 and guzzlehttp/psr7 ^3.2. Before committing, audit every package that pins older majors (PSR-7 implementations especially) and every place your own code touches promise helpers: Promise\Is is replaced by Promise\State for PHP 8.6. That's both a forward-compat signal for the PHP fleet (8.6 readiness) and a small but real code-change item.
• New cross-transport consistency risk: the stream handler now mirrors libcurl 8.14+ semantics. If production libcurl is older, the same upstream response can be accepted on the curl path and rejected on the stream path. Product decision: standardize which handler serves which workload, or explicitly test both so behavior doesn't vary by environment.
• The 8.x migration epic scope grows again: add transitive major bumps (psr7/promises), the Promise\Is → Promise\State replacement, and transfer-exception handling to the audit list from the 7.14.1 review. The earlier "~2 dev-weeks, low risk" sizing still does not transfer to a major-version boundary.
• Build vs. Buy (reaffirmed, second time): reimplementing chunked framing, Content-Length boundaries, transfer-coding rejection, and deflate/gzip trailer parity is precisely the subtle libcurl-parity work you should not hand-roll. The package is doing it for you — which is also the argument for taking these releases rather than pinning.

When to Consider This Package

Adopt 8.3.0 if:

• You use stream handlers (stream => true or custom handlers) for high-volume downloads, exports, or webhook ingestion — especially against third-party or flaky upstreams that occasionally truncate.
• You need data-integrity guarantees on body completeness and want failures surfaced as exceptions rather than short reads.
• You need PHP 8.6 readiness, or a runtime refresh is already planned.
• You can absorb guzzlehttp/psr7 ^3.2 and guzzlehttp/promises ^3.1 without conflicting pins, and have already committed to the 8.x line.
• You want a low-blast-radius, libcurl-independent release to build migration confidence before the cap+share work.

Defer or look elsewhere if:

• Your code relies on lenient stream-handler parsing — partial bodies accepted, non-standard transfer codings tolerated, trailing gzip/deflate bytes ignored. This is a behavior break, not just a fix; schedule the downstream fixes first or stay on a maintained 7.x.
• You catch specific exception types and haven't added ResponseTransferException — you will silently swallow transfer failures.
• Your fleet is on libcurl < 8.22.0 with no image refresh: the 8.2.0 cap+share headline remains inert. (Note the change from the prior assessment: this is no longer a blanket reason to defer, because 8.3.0's value doesn't depend on libcurl.)
• You only needed the 7.14.1 proxy/redaction/multiplexing fixes, have no stream-handler exposure, and have no PHP 8.6 timeline.
• You need WebSockets or non-HTTP protocols — still out of scope.

Verify before committing:

• Composer resolution against psr7 ^3.2 / promises ^3.1: all direct and transitive pins, and compatibility of whichever PSR-7 implementation you use.
• Grep for deprecated promise helpers (Promise\Is) in app code and in any vendored/first-party packages.
• Behavior diff on the stream handler for: chunked body without a terminal chunk; Content-Length short and long; Content-Length: 0; unsupported transfer codings; gzip/deflate with trailing bytes; raw deflate.
• Error-handling audit for cURL 8 and 23 — confirm retries, alerts, and dead-letter routing now match on ResponseTransferException.
• Both handler paths (curl vs. stream) against the same upstreams, to expose the 8.14+ semantics divergence on older libcurl.
• Canary metrics: transfer error rate, retry count, parse/deserialization failures, p99 and TTFB, before/after.

How to Pitch It (Stakeholders)

For Executives: "8.3.0 changes the funding story. Everything valuable in 8.2.0 was locked behind a recent libcurl, so the upgrade was really a base-image-refresh decision with no payoff until that landed. 8.3.0 delivers value on the runtime we already have: the streaming download path now enforces the declared body length, rejects truncated or malformed responses instead of silently handing us partial data, and raises a specific exception for transfers that die mid-body — which is what lets us retry and alert correctly. It also brings PHP 8.6 readiness, but it raises our minimum versions of two supporting libraries, so it is a dependency review as well as a code change. Recommendation: fund 8.3.0 as a contained hardening release targeted at our streaming workloads, with clear targets on truncated-body incidents and retry accuracy, and keep the connection-cap plus base-image-refresh initiative separately scoped as before."

For Engineering: "What changed in 8.3.0 — and it is not the same shape of change as 8.2.0: the libcurl 8.22.0 gate still applies to the cap+share feature, but the new work is runtime-independent. The stream handler now decodes chunked bodies incrementally, ends bodies at their declared Content-Length (including zero), rejects truncated/malformed chunked bodies, rejects unsupported transfer codings, matches libcurl on gzip/deflate trailing data and raw deflate, and fixes bytes arriving with headers being delayed. cURL errors 8 and 23 with a response are now ResponseTransferException. Dependency floors move to guzzlehttp/psr7 ^3.2 and guzzlehttp/promises ^3.1, and Promise\Is is replaced by Promise\State for PHP 8.6. What to do: (1) resolve dependencies and check PSR-7 implementation compatibility; (2) grep for Promise\Is; (3) build a behavior-diff test bed for the seven stream-handler cases above; (4) audit catch blocks and alerts for the new exception type; (5) run curl and stream handlers against the same upstreams to catch the 8.14+ semantics divergence if our libcurl is older; (6) re-run the 7.14.1 regression list — proxy credential parsing, integer CURLMOPT_PIPELINING, stream => true with custom handlers, NTLM + multiplexing. Ask: approval for a one-sprint 8.3.0 hardening spike with the stream-handler test bed as the deliverable."

For Developers: "8.3.0 tightens the stream handler to match libcurl — assume some previously 'working' upstreams will now throw. Handle the new type explicitly, and don't rely on lenient parsing:

use GuzzleHttp\Exception\ResponseTransferException;

try {
    $response = $client->get($url, ['stream' => true]);
    $body = $response->getBody()->getContents(); // ends at Content-Length, or throws
} catch (ResponseTransferException $e) {
    // cURL 8 (couldn't resolve/connect after partial) or 23 (write error),
    // plus truncated/malformed chunked bodies and over-length bodies.
    // Retry or dead-letter here — do NOT fall through to a generic catch.
} catch (ConnectException | RequestException $e) {
    // existing handling
}

Also: the body now stops at its declared Content-Length, including 0, so code that tolerated over-long or short reads must be fixed. Chunked bodies must end at the last chunk. Unsupported transfer codings are rejected. Gzip/deflate bodies with trailing data are rejected; raw deflate is accepted. And Promise\Is is gone in favour of Promise\State — grep before you upgrade, including vendored packages. Test the stream path against every upstream you don't control; the curl path may still be more permissive if our libcurl predates 8.14."