yansongda/pay v3.1 升级指南：PHP 7.4 门槛、PSR-11 容器与 PSR-18 HTTP 客户端的适配要点

• 后端
• 金融科技

导读：本文面向正在从 v3.0（或更早版本）升级到 yansongda/pay v3.1 的开发者，完整梳理本版本的三项核心变更——PHP 最低版本提升至 7.4、composer.json版本号约束调整，以及围绕 PSR-11（Container）与 PSR-18（HTTP Client）的依赖与初始化方式变化。读完本文，你将能根据自己所在框架（hyperf/laravel 或其它框架/无框架）准确判断升级所需的命令与代码调整，并结合当前仓库源码理解Pay::setContainer()、Pay::set()等 API 背后的实现原理，避免升级后因容器或 HTTP 客户端未正确装配而踩坑。

升级概览：v3.1 到底改了什么

v3.1 是 yansongda/pay 在 v3 系列演进中的一个"基础能力升级"版本，它本身不涉及支付接口路由的大规模变动，而是对 SDK 的运行环境与依赖装配方式做了三项关键调整，见 web/docs/v3/upgrade/v3.1.md：

1. PHP 最低版本从 7.3 提升到 7.4；
2. 版本号约束更新为~3.1.0，通过composer update完成升级；
3. 依赖策略转向 PSR 标准：php-di/php-di（PSR-11 容器）与guzzlehttp/guzzle（PSR-18 HTTP 客户端）不再作为必装依赖打包进 SDK，而是按使用场景由业务方自行安装，并通过标准接口注入。

对照当前仓库 CHANGELOG.md 中 v3.1.0 的记录，可以确认上述变更的完整事实：

• 移除php-di/php-di依赖；若使用框架非 hyperf、laravel 或未指定ContainerInterface，仍需手动安装composer require php-di/php-di；
• 移除guzzlehttp/guzzle依赖；若未指定Yansongda\Pay\Contract\HttpClientInterface，仍需手动安装composer require guzzlehttp/guzzle；
• 升级yansongda/supports到~v3.2.0；
• 升级 PHP 最低版本到7.4.0；
• 自动识别 hyperf、laravel 框架并复用其 container，减少内存占用；
• 完全支持 PSR-11，可手动传入ContainerInterface；
• Pay::config()第二个参数新增$container，支持传入ContainerInterface或Closure（Closure需最终返回ContainerInterface实例）。

说明：本文讨论的php-di/php-di方案是 v3.1 时代的官方推荐路径。SDK 在后续 v3.3 已将默认容器调整为hyperf/pimple（见 web/docs/v3/upgrade/v3.3.md），当前仓库 composer.json 的最低 PHP 版本也已演进到>=8.2。本文以 v3.1 文档为准描述当时场景，同时会标注后续变化，方便你对照理解版本演进脉络。

第一步：确认 PHP 运行环境

v3.1 将 PHP 最低版本要求从 7.3 提高到了 7.4，升级前请先确认运行环境满足条件：

php -v

如果输出显示 PHP 版本低于 7.4，需要先升级 PHP 运行环境再继续后续操作。这一门槛与 CHANGELOG 中"升级php最低版本到7.4.0"的记录一致。之所以要提高版本门槛，是因为 v3.1 全面转向 PSR 标准接口（PSR-11、PSR-18），底层依赖yansongda/supports同步升级到~v3.2.0，对运行环境提出了更高要求。

第二步：更新 composer.json 版本号并执行 composer update

在项目根目录的composer.json中，将yansongda/pay的版本约束更改为：

{ "require": { "yansongda/pay": "~3.1.0" } }

随后执行：

composer update

使用~3.1.0这样的波浪号（tilde）约束，表示允许升级到>=3.1.0且<3.2.0的所有 3.1.x 补丁版本，既能拿到 v3.1 系列内的安全修复（CHANGELOG 中可以看到 3.1.1～3.1.12 的多个补丁版本），又不会意外跨入下一个 minor 版本，避免引入新的破坏性变更。

第三步：根据框架类型决定 PSR-11 容器装配方式

v3.1 的依赖调整核心在于 PSR-11（Container Interface）。升级后，SDK 本身不再强制依赖任何具体容器实现，而是按框架自动适配或允许手动注入。具体可分为两类用户。

hyperf / laravel 用户：无需任何操作

如果您使用 hyperf 或 laravel，SDK 会在初始化时自动识别框架，并复用框架内自带的 Container，无需任何额外操作。这一行为在 CHANGELOG 中被描述为"自动识别 hyperf、laravel 框架，使用相应的 container 减少内存占用"。

其它框架 / 无框架用户：手动安装 php-di/php-di

如果您使用其它框架（包括 thinkphp）或未使用任何框架，需要额外执行：

composer require php-di/php-di

安装后，SDK 会使用php-di/php-di作为开箱即用的 Container。关于 PSR-11 装配的更完整说明，可以查阅仓库文档 安装 部分（对应文件为 web/docs/v3/quick-start/install.md）。

复用现有 PSR-11 Container（进阶）

从 v3.1 开始，Pay::config()的签名扩展为Pay::config(array $config = [], $container = null)，第二个参数可以手动传入符合 PSR-11 的ContainerInterface，或返回ContainerInterface实例的Closure。若您的框架本身已有符合 PSR-11 的 Container，可以在调用Pay::config()之前通过以下两种方式之一复用现有容器（见 web/docs/v3/quick-start/install.md）：

use Yansongda\Pay\Pay; use Yansongda\Pay\Contract\HttpClientInterface; // $container = 您现有的 container // 方法一：显式设置容器，再初始化配置 Pay::setContainer($container); Pay::config($config); // 方法二：通过 Closure 在初始化时返回容器 Pay::config($config, function () use ($container) { return $container; });

从当前仓库 src/Pay.php 的实现可以看到，Pay::config()在内部会将配置与容器转发给Artful::config()，并在初始化成功后注册事件监听（PayListener中的artfulStart/artfulEnd/httpStart/httpEnd），最后依次Artful::load()全部 11 个 Provider 的 ServiceProvider（支付宝、微信、银联、江苏银行、抖音、PayPal、Stripe、通联、翼支付、Apple 等，见 src/Pay.php）。而Pay::setContainer()则直接转发给Artful::setContainer()（见 src/Pay.php），因此"先设容器、后初始化"的时序是安全且必要的。

需要特别注意的是：Closure必须最终返回一个ContainerInterface的实例，否则后续从容器解析服务时会失败。

第四步（配套）：PSR-18 HTTP 客户端

v3.1 的 CHANGELOG 同时记录了guzzlehttp/guzzle依赖的移除——SDK 不再强制打包 HTTP 客户端，而是通过Yansongda\Pay\Contract\HttpClientInterface标准接口解耦。升级时请一并检查：

• 使用默认 Client：SDK 自带开箱即用的 HTTP 客户端实现，但仍需手动安装 Guzzlehttp：

composer require guzzlehttp/guzzle:^7.0

• 现有框架有 PSR-18 的 Client：如果您使用的框架内已有符合 PSR-18 的 HTTP Client，可以在调用Pay::config()之后（注意与容器注入的时序相反）通过以下方式复用（见 web/docs/v3/quick-start/install.md）：

use Yansongda\Pay\Pay; use Yansongda\Pay\Contract\HttpClientInterface; // $client = 您现有的 http client Pay::config($config); Pay::set(HttpClientInterface::class, $client);

Pay::set()的底层实现同样是转发给Artful::set()（见 src/Pay.php），即将自定义 HTTP 客户端注册到容器中，后续 SDK 发起网络请求时便会从容器解析该实例。当前仓库测试中大量使用这一机制注入 Mockery 构造的 mock 客户端来模拟网络请求，例如 tests/EdgeCase/NetworkEdgeCaseTest.php 中反复出现的Pay::set(HttpClientInterface::class, $http)，可以作为这一 API 用法的直接验证。

常见升级问题排查

升级过程中如果出现异常，可以按以下顺序排查：

1. Class php-di/PHP-DI\Container not found之类的容器类缺失错误：说明您是"其它框架/无框架"用户，未安装php-di/php-di，补装即可；若为 hyperf/laravel 用户，请确认是否因某些原因导致框架容器未被自动识别，必要时改用Pay::setContainer()手动注入。
2. HTTP 请求阶段报 Guzzle 相关类缺失：说明未安装guzzlehttp/guzzle也未注入自定义 PSR-18 Client，执行composer require guzzlehttp/guzzle:^7.0或按上文方式Pay::set(HttpClientInterface::class, $client)注入。
3. composer update时 PHP 版本校验失败：检查运行环境 PHP 版本是否 ≥ 7.4（v3.1 要求），后续版本要求还会进一步提高——例如 v3.4 起要求 PHP 8.0（见 web/docs/v3/upgrade/v3.4.md），当前仓库已要求>=8.2（见 composer.json）。
4. Closure 容器注入不生效：确认Closure返回值确实是ContainerInterface实例，并确保在Pay::config()调用之前完成容器准备。

版本演进脉络参考

v3.1 引入的"按框架自动适配容器 + 标准接口注入"设计，在后续版本中持续演化，了解这条脉络有助于你判断是否需要跟进升级：

• v3.3：默认容器由php-di/php-di改为hyperf/pimple，非 hyperf/laravel 或无框架用户需执行composer remove php-di/php-di && composer require hyperf/pimple（见 web/docs/v3/upgrade/v3.3.md）；
• v3.4：最低 PHP 版本提升至 8.0（见 web/docs/v3/upgrade/v3.4.md）；
• v3.6：SDK 插件系统大规模重构，内部替换为artfulAPI 请求框架（见 web/docs/v3/upgrade/v3.6.md）；
• v3.8：最低 PHP 版本提升至 8.2，Provider 运行模式统一为PayMode枚举（见 web/docs/v3/upgrade/v3.8.md）。

若您是从 v3.0 直接升级，建议同时对照 web/docs/v3/upgrade/v3.0.md 检查 v3.0 阶段的多租户配置调整与微信 v3.0 API 兼容性说明。

• 后端
• 金融科技