Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
80c1fb5
Bump version to 8.4 (#3982)
GrahamCampbell Oct 18, 2026
efe4a88
Merge branch '8.3' into 8.4
GrahamCampbell Oct 25, 2026
644f934
Merge branch '8.3' into 8.4
GrahamCampbell Oct 25, 2026
39d17ec
Sort the Cookie header by path length and replace cookies in place (#…
GrahamCampbell Oct 25, 2026
ba8613b
Add configurable idle cURL handle retention (#3993)
GrahamCampbell Oct 25, 2026
c9b7a66
Merge branch '8.3' into 8.4
GrahamCampbell Oct 25, 2026
7849540
Restore the from ini setting after overlapping stream handler transfe…
GrahamCampbell Nov 12, 2026
e65824b
Release 8.3.2
GrahamCampbell Nov 12, 2026
f72bb4c
Merge branch '8.3' into 8.4
GrahamCampbell Nov 12, 2026
ec36329
Scope stream handler error capture to the current transfer (#3996)
GrahamCampbell Nov 12, 2026
4e2b6ab
Leave an unset from ini setting untouched in the stream handler (#3997)
GrahamCampbell Nov 12, 2026
d3d6055
Release 8.4.0
GrahamCampbell Nov 12, 2026
5943ccd
Bump version to 8.5 (#3999)
GrahamCampbell Nov 12, 2026
1339729
Add a hook for replacing the default handler (#3998)
GrahamCampbell Nov 12, 2026
16a041c
Deprecate the remaining focused Utils helpers and adopt psr7 3.4 (#3983)
GrahamCampbell Nov 13, 2026
f8aca40
Release 8.5.0
GrahamCampbell Nov 13, 2026
dc275d1
Merge upstream Guzzle 8.5.0
binaryfire Nov 13, 2026
d60c32b
Validate fork handler options before the default handler factory
binaryfire Nov 13, 2026
2c3f8ab
Keep the coroutine handler limits through the default handler factory
binaryfire Nov 13, 2026
7028a14
Point the coroutine handler reference at the 8.5 branch
binaryfire Nov 13, 2026
8a05382
Stop listing #3935 as an upstream pull request carried by the fork
binaryfire Nov 13, 2026
19f0dd9
Describe max_idle_multi_handlers in upstream's words
binaryfire Nov 13, 2026
279b439
Explain how a default handler factory affects the coroutine handler
binaryfire Nov 13, 2026
a846205
Remove later cookie duplicates when the stored cookie is unchanged
binaryfire Nov 13, 2026
13b6ce5
Keep response headers out of exception traces in header parsing
binaryfire Nov 13, 2026
efb56e2
Destroy suspended fibers before restoring the from setting
binaryfire Nov 13, 2026
de36e6b
List the fork's fixes to inherited upstream bugs in the README
binaryfire Nov 13, 2026
008b807
Allow fixing inherited upstream bugs in the fork
binaryfire Nov 13, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ permissions:
contents: read

env:
COMPOSER_ROOT_VERSION: 8.3.x-dev
COMPOSER_ROOT_VERSION: 8.5.x-dev

jobs:
build-lowest-version:
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/static.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ permissions:
contents: read

env:
COMPOSER_ROOT_VERSION: 8.3.x-dev
COMPOSER_ROOT_VERSION: 8.5.x-dev

jobs:
phpstan:
Expand Down
9 changes: 6 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,9 @@ sections of the README and `UPGRADING.md` describe the fork; the rest of

- Keep fork changes minimal and in upstream's style so upstream updates merge
cleanly.
- Fix confirmed upstream bugs that warrant correction in the fork. Add a concise
code comment explaining why the fix differs from upstream. Do not open an
upstream pull request unless the owner asks.
- Track the latest stable upstream release. Sync when a new stable release is
available, merging all changes through its release commit and preserving the
fork's intentional differences. Do not routinely sync unreleased branch
Expand Down Expand Up @@ -130,9 +133,9 @@ sections of the README and `UPGRADING.md` describe the fork; the rest of
never a rebase. Review the full upstream diff since the previous sync and the
resulting fork diff; keep the fork's intentional behavior when resolving
conflicts.
When upstream merges a pull request the fork already carries, reconcile the
fork's copy with upstream's final version, keep the fork's own changes on top
of it, and remove only the code it supersedes.
When upstream merges a fix the fork already carries, reconcile the fork's copy
with upstream's final version, keep the fork's own changes on top of it, and
remove only the code it supersedes.
- Run the fork's static checks and relevant unit tests using the existing local
environment, then push the pull request branch. Use the `gh` CLI to monitor
CI and inspect failure logs. CI runs the full suite, including integration
Expand Down
41 changes: 41 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,47 @@ and the README's [Hypervel Fork](README.md#hypervel-fork) section.
Please refer to [UPGRADING](UPGRADING.md) guide for upgrading to a major version.


## 8.5.0 - 2026-11-13

### Added

- Add `Utils::setDefaultHandlerFactory()` to replace the default handler

### Changed

- Adjusted `guzzlehttp/psr7` version constraint to `^3.4`

### Deprecated

- Deprecated `Utils::defaultUserAgent()` in favor of `ClientInterface::MAJOR_VERSION`
- Deprecated `Utils::headersFromLines()`, `Utils::normalizeHeaderKeys()`, `Utils::debugResource()`, and `Utils::normalizeProtocols()`


## 8.4.0 - 2026-11-12

### Added

- Add `max_idle_handles` client and cURL handler option to limit idle handles

### Changed

- Adjusted `guzzlehttp/psr7` version constraint to `^3.3`
- Send longer-path cookies first in the `Cookie` header, like browsers and libcurl
- Replace stored cookies in place so a refreshed cookie keeps its position in the `Cookie` header

### Fixed

- Fix overlapping stream handler transfers swallowing and mixing up PHP errors
- Fix the stream handler sending an empty `From` header with no `from` ini set


## 8.3.2 - 2026-11-12

### Fixed

- Fix overlapping stream handler transfers leaving the `from` ini setting blank


## 8.3.1 - 2026-10-25

### Fixed
Expand Down
7 changes: 3 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,10 +53,9 @@ Guzzle client, including clients that SDKs create. This fork adds:
and each easy handle has its own connection cache, so with 3 most concurrent
requests would open new connections. `CurlMultiHandler` keeps its default of
50. See [Idle cURL Handles](docs/handlers.md#idle-curl-handles).
- **Upstream pull requests.** The fork includes
[#3935](https://github.com/guzzle/guzzle/pull/3935), which adds the
`max_idle_handles` option for the cURL handlers. Stream handling fixes use
upstream's implementations.
- **Fixes not in upstream.** Setting a cookie the jar already holds also removes
stored cookies that were changed into duplicates of it. Response header
parsing keeps headers out of exception traces, as they can carry credentials.

> [!IMPORTANT]
> This fork keeps upstream's public API. Once installed, it replaces
Expand Down
5 changes: 3 additions & 2 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -54,10 +54,11 @@
"php": "^8.4",
"ext-json": "*",
"ext-swoole": "*",
"guzzlehttp/psr7": "^3.2",
"guzzlehttp/psr7": "^3.4",
"hypervel/guzzle-promises": "^3.1",
"psr/http-client": "^1.0",
"psr/http-factory": "^1.0",
"symfony/deprecation-contracts": "^2.5 || ^3.0",
"symfony/polyfill-php80": "^1.25",
"symfony/polyfill-php82": "^1.27"
},
Expand Down Expand Up @@ -88,7 +89,7 @@
"name": "guzzle/client-integration-tests",
"version": "v4.0.1",
"require": {
"guzzlehttp/psr7": "^3.2",
"guzzlehttp/psr7": "^3.4",
"php": "^7.4 || ^8.0",
"php-http/message": "^1.0 || ^2.0",
"phpunit/phpunit": "^9.6.34",
Expand Down
12 changes: 7 additions & 5 deletions docs/contributing/curl-connection-reuse.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,13 @@ connections alive in a **connection cache** and reuses them for later transfers
on the same handle — or across handles, if you share them (§3).

`CurlFactory` pools easy handles: on `release()` it calls `curl_reset()` (which
clears per-request options) and returns the handle to a small pool; `create()`
pops a pooled handle and re-applies the next request's options. The key fact:
**`curl_reset()` does not close the underlying connection** — reuse is the
whole point — so a pooled handle can carry a live connection from one request
into the next.
clears per-request options) and returns the handle to a pool of at most
`max_idle_handles` idle handles (by default 256 for `CurlHandler` and 50 for
`CurlMultiHandler`), closing it instead when the pool is full; `create()` pops a
pooled handle and re-applies the next request's options. The key fact:
**`curl_reset()` does not close the underlying connection** — reuse is the whole
point — so a pooled handle can carry a live connection from one request into the
next.

The option pipeline is: Guzzle request options (`proxy`, `cert`, …) → an
internal `$conf` array of `CURLOPT_* => value` → `curl_setopt_array()`.
Expand Down
4 changes: 2 additions & 2 deletions docs/cookies.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,8 @@ Different implementations exist for the `GuzzleHttp\Cookie\CookieJarInterface` :
The built-in `CookieJar` admits at most 50 cookies from one response. It ignores
any `Set-Cookie` field value longer than 8,190 bytes. A generated `Cookie`
header contains at most 150 stored cookies, and its canonical line including
`Cookie: ` is limited to 8,190 bytes. Later cookies are omitted after either
output limit is reached.
`Cookie: ` is limited to 8,190 bytes. Cookies stored later are omitted after
either output limit is reached.

You can manually set cookies into a cookie jar with the named constructor
`fromArray(array $cookies, $domain)`.
Expand Down
6 changes: 3 additions & 3 deletions docs/guzzle-and-psr-7.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
This page covers how Guzzle integrates PSR-7 requests, responses, streams, and
URIs while sending HTTP requests. Generic PSR-7 message, URI, stream, and helper
documentation lives in
[`guzzlehttp/psr7`](https://github.com/guzzle/psr7/blob/3.2/README.md).
[`guzzlehttp/psr7`](https://github.com/guzzle/psr7/blob/3.4/README.md).

## Sending PSR-7 Requests

Expand Down Expand Up @@ -34,7 +34,7 @@ middleware and handlers.
Guzzle uses PSR-7 stream objects to represent request and response bodies. For
general stream creation, metadata, decorators, and PHP stream resource
integration, see the
[PSR-7 stream documentation](https://github.com/guzzle/psr7/blob/3.2/docs/streams-and-decorators.md).
[PSR-7 stream documentation](https://github.com/guzzle/psr7/blob/3.4/docs/streams-and-decorators.md).

For response bodies, the built-in stream handler creates or wraps the
sink/default stream with the configured
Expand Down Expand Up @@ -86,4 +86,4 @@ itself is created with the

- [Quick Start](quick-start.md)
- [Request Options](request-options.md)
- [PSR-7 stream documentation](https://github.com/guzzle/psr7/blob/3.2/docs/streams-and-decorators.md)
- [PSR-7 stream documentation](https://github.com/guzzle/psr7/blob/3.4/docs/streams-and-decorators.md)
74 changes: 54 additions & 20 deletions docs/handlers.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,37 @@ system.
> have a cookie middleware associated with a client, then setting the `cookies`
> request option will have no effect on the request.

### Default Handler Factory

`GuzzleHttp\Utils::setDefaultHandlerFactory()` sets a factory that creates the
default handler in place of the built-in selection. The factory receives the
handler options and a callable that returns the handler Guzzle would have
chosen:

```php
use GuzzleHttp\Middleware;
use GuzzleHttp\Utils;
use Psr\Http\Message\RequestInterface;

$factory = function (array $handlerOptions, callable $default): callable {
$addHeader = Middleware::mapRequest(function (RequestInterface $request) {
return $request->withHeader('X-Foo', 'bar');
});

return $addHeader($default());
};

Utils::setDefaultHandlerFactory($factory);
```

The factory is consulted each time a default handler is chosen, after the
handler options have been checked for type and value. Clients that already exist
keep their handler, and a handler provided explicitly never reaches the factory.
Passing null restores the built-in selection.

The factory is process-wide, so set it from application bootstrap code, not from
a library.

### PSR-17 Factories

The PSR-17 factory request options are owned by different layers:
Expand Down Expand Up @@ -102,10 +133,9 @@ custom handlers are responsible for honoring these options themselves.
### Idle cURL Handles

`max_idle_handles` (int|null): Maximum number of idle cURL easy handles retained
by each default cURL handler. Accepts a non-negative integer or null. Zero
disables idle handle retention; null or omission keeps the defaults of 256 for
`CurlHandler` and 50 for `CurlMultiHandler`. This setting does not affect the
stream handler.
by each default cURL handler. Zero disables retention; null or omission keeps
the defaults of 256 for `CurlHandler` and 50 for `CurlMultiHandler`. This
setting does not affect the stream handler.

Pass this option to the client constructor when Guzzle creates the default
handler:
Expand All @@ -118,23 +148,24 @@ $client = new Client([
]);
```

One value applies separately to each cURL handler Guzzle creates. In this
example, both the synchronous and asynchronous handlers retain at most 64 idle
easy handles each. Handles are created as requests need them, not allocated in
advance.
In this example, the synchronous and asynchronous handlers each retain at most
64 idle easy handles. Handles are created as requests need them, not allocated
in advance.

Keeping more idle easy handles can improve reuse after concurrent requests,
particularly when a coroutine runtime allows synchronous requests to overlap. It
also retains more native resources. This is not a limit on active requests or
network connections: a synchronous easy handle can cache connections to several
origins, and `CurlMultiHandler` has its own connection cache separate from its
idle easy handles.
Retaining more idle handles can improve connection reuse when synchronous
requests overlap, such as under a coroutine runtime, at the cost of more native
resources. It does not limit active requests or network connections: a
synchronous easy handle can cache connections to several origins, and
`CurlMultiHandler` has its own connection cache separate from its idle easy
handles. A handle released into a full pool is closed with the connections it
holds, so zero makes every synchronous request open a new connection unless
persistent transport sharing pools connections, while `CurlMultiHandler` keeps
reusing them through its multi handle.

The option is also accepted by `GuzzleHttp\Utils::chooseHandler()` and the
`CurlHandler` and `CurlMultiHandler` constructors. A non-null value cannot be
combined with a custom client handler or a custom `handle_factory`: configure
the option on the custom handler's constructor, or retention on the custom
factory, instead.
combined with a custom client handler or a custom `handle_factory`; configure
the cURL handler or the factory instead.

### Closing cURL Handlers

Expand Down Expand Up @@ -208,10 +239,13 @@ connection caps are configured. Synchronous requests still use `CurlHandler`.
One client can serve concurrent coroutines; each promise must still be created
and completed in its owning coroutine.

The callable passed to a [default handler factory](#default-handler-factory)
returns this default handler, so a factory that wraps it keeps the coroutine
handler. A factory that creates its own handler replaces it.

`max_idle_multi_handlers` (int|null): Maximum number of idle cURL multi handlers
retained for coroutine requests. Accepts a non-negative integer or null. Zero
disables retention; null or omission keeps the default of 64. Cannot be combined
with connection caps or a custom handler.
retained for coroutine requests. Zero disables retention; null or omission keeps
the default of 64. Cannot be combined with connection caps or a custom handler.

```php
$client = new \GuzzleHttp\Client(['max_idle_multi_handlers' => 16]);
Expand Down
4 changes: 2 additions & 2 deletions docs/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ curl -sS https://getcomposer.org/installer | php
You can add Guzzle as a dependency using Composer:

```bash
composer require hypervel/guzzle:^8.3
composer require hypervel/guzzle:^8.5
```

Alternatively, you can specify Guzzle as a dependency in your project's existing
Expand All @@ -39,7 +39,7 @@ composer.json file:
```js
{
"require": {
"hypervel/guzzle": "^8.3"
"hypervel/guzzle": "^8.5"
}
}
```
Expand Down
2 changes: 1 addition & 1 deletion docs/package-ecosystem.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ application needs that package's lower-level or specialized behavior.
| Package | Use it for | Documentation |
|---------|------------|---------------|
| `hypervel/guzzle` | Sending synchronous and asynchronous HTTP requests. | [Quick Start](quick-start.md) |
| `guzzlehttp/psr7` | Creating and manipulating PSR-7 requests, responses, streams, and URIs. | [PSR-7 docs](https://github.com/guzzle/psr7/blob/3.2/docs/psr-7-messages.md) |
| `guzzlehttp/psr7` | Creating and manipulating PSR-7 requests, responses, streams, and URIs. | [PSR-7 docs](https://github.com/guzzle/psr7/blob/3.4/docs/psr-7-messages.md) |
| `hypervel/guzzle-promises` | Working directly with promises returned by asynchronous operations. | [Promises docs](https://github.com/hypervel/guzzle-promises/blob/3.1/docs/promise-quick-start.md) |

Install `hypervel/guzzle` for normal application HTTP work. It already depends
Expand Down
2 changes: 1 addition & 1 deletion docs/request-options.md
Original file line number Diff line number Diff line change
Expand Up @@ -2013,7 +2013,7 @@ response body resources where practical. Request bodies that already implement
> gzip/deflate decoding, and should stream the resource rather than buffer it
> entirely into memory. The full contract is described under *Creating Streams*
> in the
> [PSR-7 stream documentation](https://github.com/guzzle/psr7/blob/3.2/docs/streams-and-decorators.md#creating-streams).
> [PSR-7 stream documentation](https://github.com/guzzle/psr7/blob/3.4/docs/streams-and-decorators.md#creating-streams).
> Supply a stream implementation you trust.

## uri_factory
Expand Down
Loading