Composer如何迁移guzzlehttp/guzzle版本_Composer迁移guzzle版本实战

直接升级 Guzzle 到 7.x/8.x 易破坏调用逻辑，因 v7+ 改为 Promise-first 异步默认、移除 send()、重命名配置项；v8+ 更强制异步且要求 PHP 8.0+，须改用 getAsync() 并处理 Promise。

直接升级 guzzlehttp/guzzle 到 7.x 或 8.x 版本，听起来是个简单的版本号跳跃，但实际操作起来，很可能让你的现有 HTTP 客户端调用逻辑瞬间“罢工”。特别是如果你的项目里还在沿用 send()、request() 的返回值解构，或者手动构造 Request 对象——这些在 v7 及以后的版本里，已经被彻底重构，转向了 Promise-first 和默认异步的行为模式。

确认当前版本和依赖链

升级的第一步，不是急着改代码，而是先看清楚“拖后腿”的到底是谁。很多时候，问题不在于你的代码直接依赖了 Guzzle，而是某个你正在使用的 SDK（比如 aws/aws-sdk-php 或 spatie/lara vel-backup）锁定了旧版本。打开终端，运行下面这条命令，看看现状：

composer show guzzlehttp/guzzle

紧接着，再查一下究竟是哪些包在依赖它：

composer depends guzzlehttp/guzzle

排查过程中，下面这几种情况相当常见：

• lara vel/framework v8 及更早的版本，默认会拉取 guzzlehttp/guzzle ^6.5，直到 v9+ 才开始适配 v7+。
• 像 php-http/guzzle6-adapter 这类桥接包，会硬性依赖 v6 版本，不把它处理掉，升级就无从谈起。
• 如果你自定义了 GuzzleHttp\Client 的子类，并且重写了 send() 方法，那可得注意了：这个方法在 v7+ 中已被移除，必须改用 execute() 或 requestAsync()。

升级到 v7.x 的最小改动路径

v7 版本可以看作是一个兼容性的过渡版，它保留了同步调用的使用习惯，但底层已经基于 PSR-18 和 Promises 进行了重构。升级到这一版，关键动作有几个：

• 执行 composer require guzzlehttp/guzzle:^7.5（这里有个小建议：别用 ^7.0，早期的 v7 版本存在 stream 资源泄漏的 bug）。
• 把所有类似 $client->get($url) 的调用，改成 $client->get($url)->getBody()->getContents()。原因在于，v7+ 返回的是 ResponseInterface，不再自动解包 body 内容。
• 检查代码是否还在使用 GuzzleHttp\Ring：这个命名空间早在 v6 就已废弃，v7 更是彻底删除，相关的 RingPHP 适配器将全部失效。
• 如果配置中使用了 curl.options 这样的配置项，需要改为 curl 数组键（例如 ['curl' => [CURLOPT_TIMEOUT => 5]]），v7 不再识别旧的 key 名。

跳过 v7 直升 v8/v9 的硬约束

如果你打算一步到位，直接跳到 v8 或更新的版本，那么面对的将是更严格的约束。v8+ 移除了所有同步阻塞方法，get()、post() 等全部返回 PromiseInterface，并且要求 PHP 版本至少是 8.0（v9 要求 8.1+）。强行升级，立刻就会看到类似这样的错误：

Call to undefined method GuzzleHttp\Client::get()

到了这一步，必须做好以下准备：

• 确认你的项目已经启用了 async/await 支持（比如使用了 ReactPHP、Amp，或者 Lara vel 的 Http::pool()）。
• 把所有形如 $client->get(...) 的调用，替换为 await $client->getAsync(...)->then(...) 的模式，或者封装成 Promise\Utils::wait()（注意：后者仅限 CLI 或测试环境，不要用于 Web 请求）。
• 删除所有对 GuzzleHttp\Handler\CurlMultiHandler 的直接引用——v8 改用 HandlerStack 统一管理，curl_multi 不再作为公共类暴露。
• 留意 verify 选项的默认值从 true 变成了 system。如果你之前为了绕过证书校验而设置了 false，现在需要显式地写上 'verify' => false。

最后，还有一个最容易被忽略的细节：中间件的执行顺序。v7+ 的 HandlerStack 默认已经插入了重试、cookie、重定向等中间件。如果你之前的代码是依靠手工拼接 handler 链来控制流程的，升级后其行为可能会发生静默的变化。稳妥的做法是，使用 $stack->remove('retry') 显式地清理默认栈，然后再按需添加你自己的中间件，而不是想当然地依赖默认的栈结构。