Hyperf v3.2 升级指南:破坏性变更、配置迁移与新增能力全解析
Hyperf v3.2 升级指南:破坏性变更、配置迁移与新增能力全解析
Hyperf v3.2 是 3.x 系列的一次重要迭代(首个版本 v3.2.0 于 2026-06-07 发布,随后通过 v3.2.1、v3.2.2、v3.2.3、v3.2.4 持续修补),其核心工作集中在三方面:一是对 logger、cache、async-queue 等组件配置结构进行标准化重构(包含破坏性变更);二是针对 PHP 8.4、elasticsearch 8/9.x、Carbon v3 等上游生态做兼容升级;三是清理了大量历史废弃代码。本文以仓库内 docs/zh-hk/changelog/3.2.md 为骨架,结合源码实现逐项展开,帮助你在升级到 v3.2 时准确完成配置迁移、规避行为变化带来的坑,并第一时间用上新增能力。
一、版本线概览:v3.2.0 → v3.2.4
| 版本 | 发布日期 | 主要内容 |
|---|---|---|
| v3.2.0 | 2026-06-07 | 破坏性变更(Carbon、async-queue、logger、cache、swow)、依赖升级、大批废弃代码移除、新增能力集中落地 |
| v3.2.1 | 2026-06-15 | 修复 gen:model 继承重写、新增无 set_error_handler 的 StreamHandler、优化 Timer::tick() 协程上下文 |
| v3.2.2 | 2026-07-26 | 移除第二批废弃代码、修复多项验证/迁移/扫描/预加载缺陷 |
| v3.2.3 | 2026-07-29 | 新增 existent() 函数、修复模型 @property 类型标注与 phpdoc |
| v3.2.4 | 2026-08-10 | 新增 assert_instanceof()、Nacos 多版本实例主机读取、日志目录竞态修复 |
整体升级建议:先处理下面的破坏性变更,再逐步跟进补丁版本。
二、破坏性变更(升级必读)
1. Carbon 组件行为变更
Carbon::createFromTimestamp()在 v3.2(配合 Carbon v3.0)中不再通过date_default_timezone_get()读取默认时区,使用方式需要显式传入时区参数。Carbon::diffInDays()默认不再返回绝对值,如需绝对值必须显式传入$absolute参数。
<?php
use Carbon\Carbon;
$t = time();
// 不兼容的用法(依赖默认时区读取)
Carbon::createFromTimestamp($t, date_default_timezone_get());
// 正确的用法(显式指定时区)
Carbon::createFromTimestamp($t, date_default_timezone_get());
diffInDays() 的语义变化尤其容易在“计算两个日期相差几天”的业务中出现符号反转,升级后建议自查所有调用点,按需补上 $absolute = true。
2. async-queue:getQueueName() 重命名为 getPoolName()
为了术语一致性(队列实例在实现上对应“连接池 pool”),JobInterface::getQueueName() 被重命名为 getPoolName()。源码层面,接口定义与默认实现均已切换为新名称:
- 接口声明见 src/async-queue/src/JobInterface.php;
- 基类默认实现返回
'default',见 src/async-queue/src/Job.php; - 派发函数
dispatch()会在未显式指定 pool 时回退到$job->getPoolName(),见 src/async-queue/src/Functions.php。
因此所有自定义 Job 需要同步迁移:
<?php
// 变更前
class CustomJob extends \Hyperf\AsyncQueue\Job
{
public function getQueueName(): string
{
return 'custom';
}
}
// 变更后
class CustomJob extends \Hyperf\AsyncQueue\Job
{
public function getPoolName(): string
{
return 'custom';
}
}
配套变更:ConsumerProcess 的 $queue 属性也重命名为 $pool(对应 src/async-queue/src/Process/ConsumerProcess.php),进程名由 queue.{$pool} 生成。
3. logger 配置结构变更
旧结构是“default 直接承载驱动配置”,新结构引入了 channels 分层:顶层 default 只存放默认 channel 名称字符串,具体配置下沉到 channels 下。变更细节见 src/logger/publish/logger.php 与 src/logger/src/LoggerFactory.php。
<?php
// 变更前
return [
'default' => [
'driver' => 'daily',
'path' => BASE_PATH . '/runtime/logs/hyperf.log',
'level' => env('LOG_LEVEL', 'debug'),
'days' => 7,
],
];
// 变更后
return [
'default' => 'default',
'channels' => [
'default' => [
'driver' => 'daily',
'path' => BASE_PATH . '/runtime/logs/hyperf.log',
'level' => env('LOG_LEVEL', 'debug'),
'days' => 7,
],
// 在此处添加你自定义的 channel
],
];
从源码看,LoggerFactory 构造函数 对旧式配置做了兼容兜底(检测到缺少 logger.channels 或 logger.default 仍是数组时自动包装为 ['default' => 'default', 'channels' => 旧配置]),make()/get() 均按 logger.channels.{channel} 读取。升级后建议立即改用新结构,以获得多 channel 命名与独立 handler/formatter 组合能力——官方发布配置中已经预置 stack、single、daily、stderr、syslog、null 六个 channel 模板。
4. cache 配置结构变更
与 logger 同步,cache 配置改为 stores 多存储结构:顶层 default 用 env('CACHE_DRIVER', 'default') 指定默认存储名,各存储配置下沉到 stores。官方发布配置见 src/cache/publish/cache.php。
<?php
// 变更前
return [
'default' => [
'driver' => RedisDriver::class,
'packer' => PhpSerializerPacker::class,
'prefix' => 'c:',
],
];
// 变更后
return [
'default' => env('CACHE_DRIVER', 'default'),
'stores' => [
'default' => [
'driver' => RedisDriver::class,
'packer' => PhpSerializerPacker::class,
'prefix' => 'c:',
],
],
];
注意发布配置中 default store 还包含 skip_cache_results 与 options.pool 等字段,其中 options.pool 指向 Redis 连接池名称(默认 'default')。CacheManager 同样内置了对旧配置的兼容判断(当 cache.stores 不存在或 cache.default 为数组时自动转换),但推荐按新结构显式迁移。
5. 使用 swow 驱动时需要新增依赖绑定
如果使用 Swow 引擎,需要在 config/autoload/dependencies.php 中显式声明响应发射器实现:
<?php
use Hyperf\Contract\ResponseEmitterInterface;
use Hyperf\Engine\ResponseEmitter;
return [
ResponseEmitterInterface::class => ResponseEmitter::class,
];
这一变更意味着从 v3.2 起,框架不再隐式绑定 Swow 场景下的响应发射器,升级到 Swow 运行环境时必须补齐上述映射。
三、PHP 8.4 注意事项:fgetcsv / fputcsv 的 escape 参数
如果你已将运行时升级到 PHP 8.4,fgetcsv 与 fputcsv 现在要求为 escape 参数提供默认值,否则会抛出弃用警告甚至报错。涉及 CSV 读写的位置必须显式传 escape: '':
fputcsv($fp, $fields) 必须修改为 fputcsv($fp, $fields, escape: '')
fgetcsv($fp) 必须修改为 fgetcsv($fp, escape: '')
与之呼应,v3.2 中 str_getcsv 的内部实现也已改为使用空字符串作为 escape(见“行为变更”章节),保证 CSV 解析行为在 PHP 8.4 下保持一致。
四、依赖升级清单
v3.2 对运行环境与关键依赖提出了新的版本要求,升级前请先核对 composer 约束:
- PHP 版本升级至
>=8.2 elasticsearch/elasticsearch升级至^8.0 || ^9.0nikic/php-parser升级至5.6symfony/*组件升级至^6.0 || ^7.0phpunit/phpunit升级至^11.0google/protobuf升级至^3.6.1 || ^4.2guzzlehttp/guzzle升级至^7.0nesbot/carbon支持v3.0(与上述 Carbon 行为变更配套)- Monolog 不再支持 2.x,仅支持 3.x(对应 src/logger/publish/logger.php 中
Monolog\Level等 3.x API 的使用)
五、移除的废弃代码(Removed)
v3.2 集中清理了历史欠账,升级后若仍引用以下符号会直接报错,需提前替换:
- 移除废弃的
laminas/laminas-mime包。 - 移除废弃的
Hyperf\Serializer\Contract\CacheableSupportsMethodInterface接口。 - 移除
Hyperf\AsyncQueue\JobMessage序列化中的向后兼容代码。 - 按计划移除的废弃代码:Collection 向后兼容代码、ProxyTrait 参数映射、
ResumeExitCoordinatorListener、SocketIO Future 的flag参数、WebSocketHandeShakeException拼写错误别名(正确拼写为HandShakeException)。 - v3.2.2 追加移除:
ConsumerProcess::$queue向后兼容支持(改用$pool)、forceIndexes()(改用forceIndex())、str_replace_once()(改用strReplaceOnce())、ClassLoader::loadDotenv()、GrpcClient::hanldeNaming()(原拼写错误,改用handleNaming())、Watcher 旧版配置回退机制,以及废弃的RuleCollector、Tracer\Adapter\HttpClientFactory、Tracer\Aspect\JsonRpcAspect、ViewEngine\Contract\Enumerable别名。
建议升级后用全局搜索(如 grep -r "getQueueName\|forceIndexes\|str_replace_once" app/)检查残留引用。
六、优化(Optimized)
基础设施与性能
- 优化
Hyperf\Di\ReflectionManager::getAllClassesByFinder()从文件读取内容的实现(PR #6804),减少反射扫描阶段的开销。 - 事件监听器提供者为非匿名事件类增加缓存,避免重复的监听器解析(PR #7658)。
Arr::shuffle增强为支持自定义随机引擎(PR #7142);toCssClasses/toCssStyles直接使用输入数组简化逻辑(PR #7431)。- 使用 PHP 8.4+ 函数(带 polyfill)现代化 array 工具与 JSON 校验逻辑(PR #7523),意味着低版本 PHP 通过 polyfill 保持行为一致。
- 新增 Symfony 7.4 兼容性,支持批量命令注册(PR #7620)。
协程与日志
Hyperf\Coordinator\Timer::tick()的回调现在运行在Hyperf\Coroutine\wait()内部,确保定时任务在独立、受管理的协程上下文中执行;同时wait()方法会优先检查容器中是否存在Hyperf\Coroutine\Waiter(PR #7761)。- 优化
StreamHandler在协程并发场景下创建日志目录时的竞态问题(PR #7796,v3.2.4)。 StdoutLogger输出格式新增时间戳前缀(PR #7621)。
gRPC 与 Nacos
Parser::parseResponse返回值从Grpc\StringifyAble替换为Google\Rpc\Status对象,标准化错误信息的携带方式(PR #7653)。- 支持 Nacos v1、v2 及 v3 从实例列表中读取主机地址(PR #7790,v3.2.4)。
七、新增能力(Added)
1. 辅助函数:existent() 与 assert_instanceof()
v3.2.3 与 v3.2.4 分别新增两个 Hyperf\Support 命名空间下的全局函数,实现位于 src/support/src/Functions.php:
existent(mixed $value): mixed:确保值不为null,遇null抛出InvalidArgumentException,常用于收窄“可能为空”的类型推断,配合 PHPStan 的@phpstan-assert !null注解实现静态分析收窄。assert_instanceof(mixed $value, string $interface): mixed:断言值实现指定接口/类,失败时抛出包含实际类型信息的InvalidArgumentException,成功则原样返回,可用于依赖注入边界校验与测试断言。
<?php
use function Hyperf\Support\existent;
use function Hyperf\Support\assert_instanceof;
$config = existent($this->config->get('app.key')); // null 时抛异常
$listener = assert_instanceof($listener, ListenerInterface::class); // 类型不符时抛异常
2. 异步队列(async-queue)
- 支持根据
job指定队列名称(PR #6538):dispatch()在未传 pool 参数时自动回退到$job->getPoolName(),见 src/async-queue/src/Functions.php;@AsyncQueueMessage注解也支持pool属性,见 src/async-queue/src/Annotation/AsyncQueueMessage.php。 - 新增消费者进程的配置自动注册模式(PR #7618):只需在
config/autoload/async_queue.php中为对应 pool 设置'enable' => true,ConsumerManager便会遍历async_queue配置并为每个启用项自动创建消费者进程(进程名queue.{$pool},进程数取processes配置),无需再手动在config/autoload/processes.php中注册。实现见 src/async-queue/src/ConsumerManager.php,发布配置模板见 src/async-queue/publish/async_queue.php。
// config/autoload/async_queue.php
return [
'default' => [
'enable' => true, // 是否自动注册消费者进程(v3.2 新特性)
'driver' => RedisDriver::class,
'redis' => ['pool' => 'default'],
'channel' => '{queue}',
'timeout' => 2,
'retry_seconds' => 5,
'handle_timeout' => 10,
'processes' => 1, // 消费者进程数
'concurrent' => ['limit' => 10],
'max_messages' => 0,
],
];
3. 契约与集合
Hyperf\Contract\Jsonable新增toJson方法(PR #6761)。- 为 HTTP 响应新增
Htmlable契约接口(PR #6794),允许响应对象直接输出 HTML。 Hyperf\Pipeline\Pipeline::finally()(PR #7247):在管道末端追加最终回调,适合统一收尾逻辑。Hyperf\Collection\Collection::shift()/pop()支持一次取出多个元素(PR #7274)。Hyperf\Collection\Arr新增partition()与reject()(PR #7302)。Hyperf\Context\Context支持Macroable(PR #7312),可为其动态扩展方法。Hyperf\Support\Fluent得到改进(PR #7214)。
4. 数据库与测试
- 新增
hyperf/database-sqlserver包(PR #7717),SQL Server 支持独立成包,见仓库 src/database-sqlserver。 - 新增 PHP 8.4 的 PDO 子类支持(PR #7019)。
QueryException新增连接名(PR #7198),排查数据库异常时能直接定位到具体连接。- 新增
NonCoroutine注解(PR #7605),用于灵活控制测试执行方式(标注的方法/类在测试中可脱离协程环境运行)。
5. 搜索引擎
- 新增对 elasticsearch
8.x(PR #7202)与9.x(PR #7629)的支持,配合依赖升级^8.0 || ^9.0,可在新版 ES 集群上直接使用。
八、行为变更(Changed)
hyperf/database中deleted_at的默认类型变更为datetime(PR #6760),软删除时间列的生成与迁移结果随之变化。Hyperf\Database\Query\Builder::limit()在传入值小于零时抛出异常(PR #7208),阻止非法 SQL 生成。str_getcsv使用空字符串作为escape(PR #7372),与 PHP 8.4 的默认要求对齐。influxdb/influxdb-php替换为influxdata/influxdb-client-php(PR #7462),使用 InfluxDB 的组件需调整客户端 API 调用方式。- 变更
logger与cache的配置结构(见上文破坏性变更第 3、4 条)。 - async-queue 术语统一:
$queue→$pool、getQueueName()→getPoolName()。
九、修复(Fixed)
v3.2.0 修复
- 修复
sortByMany()与sortBy()返回结果不一致的 bug(PR #6934)。
v3.2.1 修复与优化
- 修复
ModelRewriteInheritanceVisitor无法在gen:model脚本中使用的问题(PR #7760)。 - 新增
Hyperf\Logger\Handler\StreamHandler,该 handler 不含set_error_handler副作用(PR #7759),避免协程场景下错误处理器被意外覆盖。 Timer::tick()与wait()的协程上下文优化(PR #7761)。
v3.2.2 修复
- 修复
Hyperf\Validation\Concerns\ValidatesAttributes::validateMultipleOf无法支持float类型校验的问题(PR #7768)。 - 修复
gen:migration-from-database命令无法使用的问题(PR #7771)。 - 修复
Hyperf\Di\ScanHandler\ProcScanHandler无法使用的问题(PR #7774)。 - 修复
MorphTo关联预加载指定字段时的 Bug(PR #7788)。
v3.2.3 修复
- 修复模型生成时
@property类型错误,例如将@property int $id修正为@property ?int $id(PR #7782),使 IDE 与静态分析能正确识别可空主键。 - 修复
Hyperf\ModelCache\Cacheable的 PHP 注释(phpdoc)(PR #7784、#7785)。 - 修复
Hyperf\Database\Model\Builder的 PHP 注释(phpdoc)(PR #7786)。
十、升级检查清单
基于上述变更,将现有项目升级到 v3.2 时可按下述清单逐项核对:
- 环境与依赖:确认 PHP
>=8.2;按“依赖升级清单”更新 composer 约束并重新composer update;若使用 Monolog 请确认已是 3.x。 - 配置迁移:将
config/autoload/logger.php迁移为default + channels结构;将config/autoload/cache.php迁移为default + stores结构;可用 src/logger/publish/logger.php 与 src/cache/publish/cache.php 作为迁移后的参考模板(也可用php bin/hyperf.php vendor:publish重新发布配置)。 - 代码重命名:全库替换
getQueueName()→getPoolName()、$queue→$pool(async-queue 相关);替换forceIndexes()→forceIndex()、str_replace_once()→strReplaceOnce()。 - 移除项清理:删除对 v3.2 已移除符号(见“移除的废弃代码”一节)的所有引用。
- Carbon 语义核对:检查所有
diffInDays()调用点,按需补充$absolute;createFromTimestamp()显式传时区。 - PHP 8.4 适配:为所有
fputcsv/fgetcsv调用补上escape: ''。 - Swow 场景:在
config/autoload/dependencies.php中绑定ResponseEmitterInterface => ResponseEmitter。 - 新特性尝鲜:按需启用 async-queue 配置自动注册(
enable => true)、NonCoroutine注解、Pipeline::finally()、existent()/assert_instanceof()等新能力。
完成以上步骤后,即可平滑过渡到 v3.2,并享受 elasticsearch 8/9.x、PHP 8.4、Symfony 7.4 等上游生态带来的红利。