Sync Guzzle 8.5.0
This updates the fork to upstream Guzzle 8.5.0, which also brings in 8.3.2 and 8.4.0. It targets a new 8.5 branch created from the current 8.3. After it merges, I'll tag 8.5.0.1, make 8.5 the default branch, delete 8.3 (keeping its tags), and update Hypervel to the new release.
What comes in from upstream
- Stream handler fixes for overlapping transfers (#3995, #3996, #3997). PHP errors raised while one transfer opens its stream are no longer captured by another transfer, and the
fromini setting is restored correctly when transfers overlap. Error capture now uses psr7'sErrorScope, which finds the active scope on the current call stack. Swoole keeps a separate call stack per coroutine, so this works across coroutines as well as fibers. - Cookie ordering (#3992). Cookies with longer paths are sent first, and a refreshed cookie keeps its place in the
Cookieheader. max_idle_handles(#3993). This is the option the fork has been carrying from #3935.Utils::setDefaultHandlerFactory()(#3998). A process-wide hook that replaces or wraps the handler Guzzle would choose by default.- Deprecated
Utilshelpers and psr7^3.4(#3983). The fork's own code doesn't call the deprecated helpers.
What changes in the fork
max_idle_handles now uses upstream's implementation. Upstream accepted the option in 8.4.0, so the fork's copy is gone and the code, messages, docs and tests are upstream's. The one difference we keep is the CurlHandler default of 256 idle easy handles instead of 3. Coroutines overlap synchronous requests on one handler, and with 3 most of those requests would open new connections.
Something to know when reviewing the merge commit: git merged both copies of the idle handle validation and tests in some files without reporting a conflict. That left duplicate test methods, which is a fatal error, and upstream's CurlHandler default of 3 ran after ours, so it would have silently replaced 256. The merge commit removes the fork's copies from those files as well as resolving the marked conflicts. The new upstream text in the cURL connection reuse reference also said 3, and now says 256.
The default handler factory keeps the coroutine handler. With no factory registered, nothing changes: the default client still leases cURL multi handlers to coroutines from a pool. The callable that a factory receives returns that same handler with the client's max_idle_handles and max_idle_multi_handlers limits. The fork checks max_idle_multi_handlers before calling the factory, the same way upstream checks its own options. A factory that builds its own handler replaces the coroutine handler, the same as passing a custom handler does today. We don't register a factory ourselves, and the handler guide now explains this.
Two upstream bugs are fixed in the fork. Review of this update found them in upstream code, and they're fixed here with a short comment at each change:
- If a stored cookie was changed into a duplicate of another, setting a cookie identical to the first one returned early and left the duplicate in the jar, so both values were sent. Upstream already drops these duplicates when the incoming cookie replaces the first match. The fork now does the same when it's unchanged.
StreamHandlermarks the raw response headers as sensitive, but theHeaderProcessormethods it passes them to didn't, and those methods throw on malformed responses. With exception arguments enabled, the trace held the full headers, includingSet-Cookie. They're now marked too, along with the deprecatedUtils::headersFromLines()forwarder.
A test that restores the from ini setting also now destroys its suspended fibers first, so a failure in it no longer leaks the setting into later tests.
AGENTS.md now says that confirmed upstream bugs are fixed in the fork with a comment explaining the difference, and that the sync reconcile step applies to any fix the fork carries.
Everything else stays. Multi handler ownership, cleanup of unfinished transfers, the handler pool and global middleware are unchanged. The new hook doesn't cover any of them. It only applies to default handlers, so clients that SDKs build with explicit handlers never reach it, and it has no ownership checks.
Why the fork doesn't shrink further
Upstream added the factory hook after deciding not to take coroutine support into core (guzzle/guzzle#3984, guzzle/promises#252). It's useful, but using it in place of the fork would lose:
- the ownership checks on promises and multi handlers;
- a reliable way to tell when a multi handler is idle, which pooling handlers between coroutines needs;
- the larger idle easy handle default for clients that SDKs build;
- global middleware coverage of clients with explicit handlers.
I also considered moving the handler pool into Hypervel and registering it through the hook. That would mean copying Guzzle's private handler selection into Hypervel and depending on internal CurlMultiHandler methods across repositories, while the fork would still be needed for everything else. Keeping the pool here is simpler.
hypervel/guzzle-promises has no new upstream release, so it doesn't change.
Commits
The merge commit holds the conflict resolution. The follow-up commits add tests for option validation and for handler limits passing through the default handler factory, update a doc link that pointed at the 8.3 branch, remove the README note about #3935, match the max_idle_multi_handlers docs to upstream's wording, and explain the factory hook in the coroutine handler docs. The last commits fix the two upstream bugs and the fiber test cleanup, list the fixes in the README and update AGENTS.md.
Testing
- PHPStan, PHP-CS-Fixer and Composer normalize pass. The regenerated PHPStan baseline is unchanged.
- I ran the affected test files locally on PHP 8.4 with Swoole. CI runs the full suite and PHP version matrix.
- I checked psr7's
ErrorScopewith overlapping Swoole coroutines that finish out of order:- each scope captured only its own errors;
- errors from unrelated coroutines reached the outer error handler;
- the outer handler was restored afterwards.