Guzzle 8.0.0 正式发布：PHP主流HTTP客户端重大破坏性版本升级

开发调优
1

# Guzzle 8.0.0 正式发布：PHP主流HTTP客户端重大破坏性版本升级
Guzzle 8.0.0 重磅破坏性版本正式发布，本次更新以**类型安全、安全加固、协议升级**为核心，底层依赖同步升级：`guzzlehttp/promises ^3.0`、`guzzlehttp/psr7 ^3.0`。
本文梳理新增特性、行为变更、废弃移除接口，并整理项目升级排查要点，方便开发者评估迁移成本。

一、核心新增功能

1. 协议与传输能力升级

  • **HTTP/3 原生支持**：PHP 8.4+ 搭配支持QUIC的libcurl，内置cURL处理器可直接发起HTTP/3请求；
  • 多路复用扩展：新增 `Multiplexing::NONE` 禁用模式，客户端、cURL多句柄、请求选项三层均可独立配置；
  • 持久化传输策略：新增两种连接共享模式
    • `PERSISTENT_PREFER`：优先复用连接
    • `PERSISTENT_REQUIRE`：强制复用连接
  • PSR-17 工厂注入：新增 `request_factory/response_factory/stream_factory/uri_factory` 请求选项，支持自定义PSR-17工厂实例。

2. 异常体系全面细化（重点影响异常捕获逻辑）

拆分原有笼统异常类型，错误定位更加精准：

  • `ConnectTimeoutException`：连接阶段超时（继承 `ConnectException`）
  • `NetworkException`：底层无响应网络故障
  • `NetworkTimeoutException`：传输层空闲超时
  • `ResponseTransferException`：响应传输异常，子类 `ResponseTimeoutException` 对应响应读取阶段超时
  • `ResponseException`：存在响应体的请求失败异常
  • `HandlerClosedException`：cURL多句柄关闭，待处理请求被拒绝时抛出

3. 安全与调试优化

  • 全部凭证参数标记 `#[\SensitiveParameter]`，PHP 8.2+ 堆栈自动脱敏，杜绝日志密钥泄露；
  • 新增 `ProxyOptions` 统一管理代理配置解析；
  • `FileCookieJar` 安全加固：切换JSON存储、文件权限限制仅所有者可读、移除PHP反序列化逻辑；
  • 内置 Basic / Digest 认证中间件，替代零散旧认证实现。

4. 其他新增能力

  • cURL处理器、Curl工厂新增显式 `close()` 生命周期方法；
  • 全量补充泛型PHPDoc注解，提升IDE智能提示与静态代码分析效果；
  • 连接池Pool回调支持传递迭代器key参数；
  • 源码全局启用 `declare(strict_types=1)`，强化全局类型一致性。

二、核心行为变更（兼容性风险点）

1. 类型安全全面收紧

所有请求选项增加前置强类型校验，非法参数直接抛出异常，不再静默兼容：
代理、超时、协议版本、延迟时间、查询参数、请求体等参数均增加类型、合法范围校验；
`SetCookie` 类全部方法与公开属性增加原生类型声明。

2. Cookie 严格对齐 RFC 6265

  • Cookie 名称区分大小写；优先读取 `Max-Age`，优先级高于 `Expires`；
  • 强制校验 `__Secure-` / `__Host-` 前缀Cookie规范，非HTTPS连接拒绝接收Secure Cookie；
  • 优化IPv6主机域名匹配逻辑，收紧域名后缀匹配规则；
  • 无 `Domain` 属性的响应Cookie，仅在当前主机生效。

3. 代理逻辑统一

  • 流处理器、cURL处理器读取 `no_proxy/NO_PROXY` 环境变量逻辑完全一致；
  • 不带端口代理地址默认使用 `1080`；非法代理URL提前校验直接报错；
  • 环境变量代理不支持HTTP/3时，自动降级 HTTP/2 / HTTP/1.1。

4. 重定向 & 超时默认参数调整

  • 仅自动跟随标准状态码：`301/302/303/307/308`；
  • 跨域重定向：Referer仅保留源站信息，不再转发认证凭证；
  • 流处理器区分双超时：`timeout` 总截止时间、`read_timeout` 空闲超时，默认60s；
  • cURL连接超时默认60秒，不再依赖PHP `default_socket_timeout`；
  • 所有HTTPS请求强制最低 TLS 1.2；
  • HTTP/2多路复用默认 `Multiplexing::WAIT`，等待连接就绪再发送请求。

5. 认证逻辑调整

  • Basic认证用户名禁止包含冒号；凭证禁止携带ASCII控制字符；
  • Digest认证优化：预授权无正文请求可复用已验证挑战，修复nonce计数；
  • 取消NTLM一等原生支持。

三、破坏性移除项（升级必核查）

1. PHP版本与依赖约束升级

  • 不再支持 PHP 7.2、PHP 7.3；最低要求PHP 7.4+
  • `guzzlehttp/promises` 要求 `^3.0`
  • `guzzlehttp/psr7` 要求 `^3.0`

2. 接口、方法废弃删除

  • 移除 `Client::__call()` 魔术方法，必须显式调用 `get()/post()` 或 `request()/requestAsync()`；
  • `ClientInterface::getConfig()` 被移除，仅实体 `Client` 保留；
  • 删除 `handler` 请求选项，处理器必须在实例化客户端时配置；
  • 移除环境变量 `GUZZLE_CURL_SELECT_TIMEOUT`，改用 `CurlMultiHandler` 构造参数 `select_timeout`；
  • 禁止直接访问 `CurlMultiHandler::$_mh` cURL资源句柄；
  • 清理废弃静态工具方法：
    `Utils::jsonEncode()/jsonDecode()`、`RetryMiddleware::exponentialDelay()`、`RequestException::wrapException()`、`Utils::isHostInNoProxy()`；
  • `RequestException` 不再支持获取响应，存在响应场景统一捕获 `ResponseException`。

四、项目升级提示

  1. 典型大版本不兼容更新，升级前全面扫描：自定义中间件、异常捕获、废弃API调用；
  2. 项目如果锁定 `psr7:2.x`、`promises:2.x`，需要同步升级配套依赖；
  3. 业务代码中通过 `RequestException` 获取响应的逻辑，重构切换至 `ResponseException`；
  4. 自研Cookie处理、代理规则、重定向拦截逻辑需要回归测试，规范校验更加严格；
  5. 依赖Guzzle7的第三方SDK不要盲目升级，等待上游官方适配Guzzle 8。

结语

Guzzle 8.0 从底层收紧类型约束、网络协议规范，重构异常、传输、认证模块，安全性与标准化程度大幅提升，但存在大量破坏性改动。
升级务必同步更新配套依赖，重点改造异常捕获、Cookie、代理相关业务代码；第三方组件未适配环境下暂缓迁移，逐条验证网络请求逻辑，避免线上故障。