PHP 主流 HTTP 客户端 Guzzle 8.0 正式发布

Guzzle 8.0.0 正式版

Guzzle 是 PHP 生态最主流的 HTTP 客户端库，8.0.0 为重大破坏性更新，于 2026 年 7 月 20 日发布。

核心迭代方向为类型安全强化、异常体系细化、协议能力升级与安全边界加固，同步升级底层依赖 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() 生命周期方法
• 全量 API 补充结构化泛型 PHPDoc 注解，IDE 补全与静态分析体验大幅提升
• 连接池 Pool 回调新增迭代器 key 参数传递
• 全源码开启 declare(strict_types=1)，类型一致性全面提升

核心行为变更（兼容性影响）

1. 类型安全全面收紧

所有请求选项前置严格类型校验，非法值直接抛出异常，不再静默兼容：

• 代理、超时、协议、延迟、查询参数、请求体等参数均新增类型与范围校验
• SetCookie 类所有方法、公共属性新增原生类型声明

2. Cookie 规范严格对齐 RFC 6265

• Cookie 名称区分大小写，优先读取 Max-Age 属性而非 Expires
• 强制校验 __Secure-/__Host- 前缀 Cookie 规则，非安全连接直接拒绝接收 Secure Cookie
• 规范 IPv6 主机的 Cookie 域名匹配逻辑，收紧域名后缀匹配规则
• 无 Domain 属性的响应 Cookie 统一按「仅当前主机生效」存储

3. 代理逻辑统一

• 流处理器与 cURL 处理器的 no_proxy/NO_PROXY 环境变量读取逻辑完全对齐
• 无端口的代理地址默认使用 1080 端口，非法代理 URL 前置校验直接拒绝
• 环境变量解析出的代理不支持 HTTP/3 时，自动降级到 HTTP/2 或 HTTP/1.1

4. 重定向与超时默认值调整

• 仅自动跟随 301/302/303/307/308 标准重定向状态码
• 跨域重定向时，Referer 头仅保留源站信息，不再转发 auth 认证选项
• 流处理器 timeout 作为总传输截止时间，read_timeout 作为空闲超时，默认 60 秒
• cURL 连接超时默认 60 秒，不再依赖 PHP 配置 default_socket_timeout
• 所有 HTTPS 请求默认强制 TLS 1.2 及以上版本
• HTTP/2 多路复用默认开启 Multiplexing::WAIT 模式，等待连接就绪后再发送请求

5. 认证逻辑调整

• Basic 认证用户名禁止包含冒号，凭证禁止包含 ASCII 控制字符
• Digest 认证优化：复用已验证挑战预授权无正文请求，修复 nonce 计数逻辑
• 移除 NTLM 认证的一等支持

破坏性移除项（升级必看）

1. 环境与依赖升级

• 停止支持 PHP 7.2、PHP 7.3
• guzzlehttp/promises 版本约束升级为 ^3.0
• guzzlehttp/psr7 版本约束升级为 ^3.0

2. 接口与方法清理

• 移除 Client::__call() 魔术方法，必须使用显式 HTTP 动词方法（get()/post() 等）或 request()/requestAsync()
• 移除 ClientInterface::getConfig()，仅保留 Client 具体类的 getConfig() 实现
• 移除 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. 若项目依赖 guzzlehttp/psr7 2.x 或 guzzlehttp/promises 2.x，需同步升级适配版本
3. 原有基于 RequestException 获取响应的代码，需改为捕获 ResponseException
4. Cookie、代理、重定向的自定义逻辑需重新验证，8.0 版本规范更严格，原有兼容行为可能失效
5. 依赖 Guzzle 7 的第三方 SDK 暂不建议直接升级，需等待对应适配版本