Hyperf v3.2 升级指南:破坏性变更、配置迁移与新特性实战
Hyperf v3.2 升级指南:破坏性变更、配置迁移与新特性实战
Hyperf v3.2 是 v3 系列中一次重要的版本迭代,包含多项破坏性变更(Breaking Changes):async-queue 组件术语统一、logger 与 cache 配置结构重构、Carbon 组件行为调整,同时引入异步队列消费者自动注册、Pipeline::finally()、NonCoroutine 测试属性等新能力,并将 PHP 最低版本提升到 8.2。本文以 CHANGELOG-3.2.md 为骨架,结合当前仓库源码逐项拆解这些变更的来龙去脉、迁移方法与升级注意事项,帮助你快速完成 v3.1 → v3.2 的平滑升级,并充分使用新版本的能力。
版本总览与升级前提
v3.2 系列版本时间线与维护状态如下:
| 版本 | 发布日期 | 主要内容 |
|---|---|---|
| v3.2.0 | 2026-06-07 | 破坏性变更集中发布,依赖大幅升级,多项新特性落地 |
| v3.2.1 | 2026-06-15 | 修复 gen:model、新增无 set_error_handler 的 StreamHandler |
| v3.2.2 | 2026-07-26 | 清理 v3.2.0 遗留的废弃代码与别名 |
| v3.2.3 | 2026-07-29 | 新增 Hyperf\Support\existent(),修复模型生成与关系预加载 |
| v3.2.4 | 2026-08-10 | 新增 assert_instanceof(),支持 nacos v3 实例读取 |
| v3.2.5 | 2026-09-15 | AMQP 消费并发自适应、校验规则类型安全增强 |
| v3.2.6 | TBD | 规划中 |
升级到 v3.2 前需要满足以下依赖前提(来自 CHANGELOG 的 Dependencies Upgrade 一节):
- PHP 版本要求提升为
>=8.2:v3.2 起不再支持 8.1 及更早版本,升级前请先确认运行环境; elasticsearch/elasticsearch升级至^8.0 || ^9.0,同时新增对 elasticsearch8.x(PR #7202)与9.x(PR #7629)的支持;nikic/php-parser升级至5.6;symfony/*组件升级至^6.0 || ^7.0,并兼容 Symfony 7.4 的批量命令注册(PR #7620);phpunit/phpunit升级至^11.0;google/protobuf升级至^3.6.1 || ^4.2;guzzlehttp/guzzle升级至^7.0;nesbot/carbon新增对 v3.0 的支持(PR #6591);- Monolog 不再支持 2.x,仅支持 3.x(PR #7714)。
v3.2.0 破坏性变更详解与迁移
v3.2.0 是本次大版本中变更最集中的一次发布,共有 5 项破坏性变更,其中 3 项涉及配置结构与 API 命名,升级时必须同步调整业务代码。
1. Carbon 组件行为调整
Carbon 组件的两项行为变化会影响时间计算逻辑:
Carbon::createFromTimestamp()不再通过date_default_timezone_get()读取默认时区(对 v3.0 的行为修正)。此前隐式依赖默认时区的写法,现在必须显式传入时区参数:
<?php
use Carbon\Carbon;
$t = time();
// 需要显式传入时区
Carbon::createFromTimestamp($t, date_default_timezone_get());
Carbon::diffInDays()默认不再返回绝对值。如需绝对值结果,需显式传入$absolute参数:
<?php
use Carbon\Carbon;
$diff = Carbon::now()->diffInDays($past, absolute: true);
从源码结构看,该变更影响所有依赖 Carbon 进行时间差计算的业务,例如统计、报表、定时任务中的天数计算,建议在升级后对相关计算结果进行回归验证。
2. async-queue:getQueueName() 更名为 getPoolName()
为了统一“队列连接池”的术语表述(PR #7625),JobInterface::getQueueName() 被重命名为 getPoolName(),同时 ConsumerProcess::$queue 属性更名为 $pool(PR #7615)。当前仓库中的 JobInterface 已定义 getPoolName(): string,Job 基类默认返回 'default':
<?php
// Before
class CustomJob extends \Hyperf\AsyncQueue\Job
{
public function getQueueName(): string
{
return 'custom';
}
}
// After
class CustomJob extends \Hyperf\AsyncQueue\Job
{
public function getPoolName(): string
{
return 'custom';
}
}
该方法的实际调用点位于 Functions.php 的 dispatch() 辅助函数中——当未显式指定 $pool 参数时,会回退读取 $job->getPoolName():
function dispatch(JobInterface $job, ?int $delay = null, ?int $maxAttempts = null, ?string $pool = null): bool
{
if (is_int($maxAttempts)) {
$job->setMaxAttempts($maxAttempts);
}
$pool ??= $job->getPoolName();
return ApplicationContext::getContainer()
->get(DriverFactory::class)
->get($pool)
->push($job, $delay ?? 0);
}
因此,只要你的 Job 类重写了 getQueueName(),升级后必须同步改为 getPoolName(),否则 dispatch() 将无法按预期路由到指定队列池。ConsumerProcess 中的 $pool 属性则决定了消费进程读取哪个队列池的驱动与配置(见 ConsumerProcess.php)。
3. logger 配置结构重构
logger 配置从“单一默认通道”改为“默认通道 + 多通道(channels)”结构(PR #7563):
<?php
// Before
return [
'default' => [
'driver' => 'daily',
'path' => BASE_PATH . '/runtime/logs/hyperf.log',
'level' => env('LOG_LEVEL', 'debug'),
'days' => 7,
],
];
// After
return [
'default' => 'default',
'channels' => [
'default' => [
'driver' => 'daily',
'path' => BASE_PATH . '/runtime/logs/hyperf.log',
'level' => env('LOG_LEVEL', 'debug'),
'days' => 7,
],
// Add your custom channels here
],
];
新结构下,default 字段是字符串,用于指定默认使用的通道名;channels 下可注册任意数量的具名通道。仓库中 logger 组件发布配置 展示了完整的通道定义方式:每个通道由 handler(含 class 与 constructor)、formatter、processors 三部分组成,并内置了 stack、single、daily、stderr、syslog、null 等通道模板。以 daily 通道为例:
'daily' => [
'handler' => [
'class' => RotatingFileHandler::class,
'constructor' => [
'filename' => BASE_PATH . '/runtime/logs/hyperf.log',
'level' => Level::Debug,
],
],
'formatter' => [
'class' => LineFormatter::class,
'constructor' => [],
],
'processors' => [],
],
迁移要点:把原 default 数组整体挪入 channels.default,再将 default 改为 'default' 字符串;自定义通道按同样的 handler/formatter/processors 结构追加即可。日志是排查线上问题的第一入口,升级时务必检查所有依赖 LoggerFactory 按通道取日志的代码。
4. cache 配置结构重构
cache 配置同样改为“默认存储 + 多存储(stores)”结构(PR #7594):
<?php
// Before
return [
'default' => [
'driver' => RedisDriver::class,
'packer' => PhpSerializerPacker::class,
'prefix' => 'c:',
],
];
// After
return [
'default' => env('CACHE_DRIVER', 'default'),
'stores' => [
'default' => [
'driver' => RedisDriver::class,
'packer' => PhpSerializerPacker::class,
'prefix' => 'c:',
],
],
];
与 logger 的迁移方式一致:原 default 数组移入 stores.default,default 字段改为存储名。当前仓库的 cache 发布配置 中,每个 store 除 driver、packer、prefix 外,还支持 skip_cache_results 与 options(如 Redis 连接池 pool),并预留了 sqlite 等备选存储的注释示例,多缓存后端共存时按需追加 store 即可。
5. swow 运行时新增依赖
使用 swow 作为运行引擎时,需要在 config/autoload/dependencies.php 中显式绑定响应发射器实现:
<?php
use Hyperf\Contract\ResponseEmitterInterface;
use Hyperf\Engine\ResponseEmitter;
return [
ResponseEmitterInterface::class => ResponseEmitter::class,
];
从代码结构看,该绑定让 HTTP 响应发射在 swow 引擎下走 Hyperf\Engine\ResponseEmitter 实现,确保协程化 IO 与事件循环兼容。若你的项目使用 swow 运行,升级 v3.2 后缺少此依赖会导致响应发射相关错误。
PHP 8.4 兼容警告:fgetcsv / fputcsv 的 escape 参数
升级到 v3.2 后,如果运行在 PHP 8.4 环境,需要注意 fgetcsv 与 fputcsv 两个函数现在必须为 escape 参数提供默认值:
fputcsv($fp, $fields) must be changed to fputcsv($fp, $fields, escape: '')
fgetcsv($fp) must be changed to fgetcsv($fp, escape: '')
这是 PHP 8.4 对 CSV 函数的签名收紧所致,涉及所有直接调用这两个原生函数的业务代码。同时,v3.2 中 str_getcsv 的 escape 参数已改为使用空字符串作为默认值(PR #7372),请一并检查相关 CSV 解析逻辑。
新增能力亮点
v3.2.0 及后续补丁版本带来了多项可直接落地的实用新特性。
异步队列消费者进程自动注册
PR #7618 新增了基于配置的异步队列消费者注册模式:只要在 config/autoload/processes.php 之外,于队列配置中开启自动注册,即可省去手动注册 ConsumerProcess 的步骤。仓库中的 async_queue.php 发布配置 第一项即为开关:
return [
'default' => [
'enable' => true, // Whether to enable auto register consumer process.
'driver' => RedisDriver::class,
'redis' => [
'pool' => 'default',
],
'channel' => '{queue}',
'timeout' => 2,
'retry_seconds' => 5,
'handle_timeout' => 10,
'processes' => 1,
'concurrent' => [
'limit' => 10,
],
'max_messages' => 0,
],
];
该机制由 ConsumerManager 实现,最终通过 ProcessManager::register() 注册消费进程。enable => true 时无需再在 processes.php 中手写 ConsumerProcess,新增队列只需追加配置项,显著降低多队列场景的维护成本。
基于 Job 指定队列名
PR #6538 支持在 Job 内部指定其所属队列池,配合上文提到的 getPoolName() 重命名,现在一个 Job 类即可通过 getPoolName() 声明自己的归属池,dispatch() 会自动路由(未显式传 $pool 时)。这为“不同任务类型分流到不同队列”提供了更自然的表达方式。
Pipeline 与集合工具增强
Hyperf\Pipeline\Pipeline新增finally()方法(PR #7247),允许在管道执行完毕后执行兜底逻辑,适用于资源清理、统一收尾等场景;Hyperf\Collection\Collection的shift()与pop()支持一次取出多个元素(PR #7274);Hyperf\Collection\Arr新增partition()与reject()(PR #7302);Hyperf\Support\Fluent能力增强(PR #7214),toCssClasses与toCssStyles直接使用输入数组简化逻辑(PR #7431),并基于 PHP 8.4+ 函数(含 polyfill)现代化了数组工具与 JSON 校验(PR #7523);- 数组
shuffle支持自定义随机引擎(PR #7142)。
Context 支持 Macroable
Hyperf\Context\Context 新增 Macroable 支持(PR #7312),可像 Laravel 集合一样为协程上下文扩展自定义宏方法,便于在业务层封装常用的上下文读写操作。
NonCoroutine 测试属性
PR #7605 新增 NonCoroutine attribute,用于灵活控制测试执行:标记后测试用例将以非协程方式运行,方便在不支持协程的环境或特定场景下执行测试,降低测试编排成本。
StdoutLogger 输出增加时间戳
PR #7621 为 StdoutLogger 的输出格式增加了时间戳前缀,开发模式下控制台日志可读性大幅提升,便于对照运行时序排查问题。
新组件:database-sqlserver
PR #7717 新增 database-sqlserver 包,Hyperf 数据库生态补齐了 SQL Server 支持,需要对接 SQL Server 的项目可直接引入该组件。
其他值得关注的新增
Hyperf\Contract\Jsonable新增toJson方法(PR #6761);- 新增
Htmlablecontract 接口(PR #6794),用于 HTTP 响应输出 HTML 片段; - PHP 8.4 下的 PDO 子类支持(PR #7019);
QueryException携带连接名(PR #7198),多库场景定位异常更直接;- 事件监听器提供器为匿名类之外的普通事件类增加了缓存,避免重复解析监听器(PR #7658);
Hyperf\Logger\Handler\StreamHandler(v3.2.1,PR #7759):一个不包含set_error_handler的 StreamHandler 变体,避免与框架自身的错误处理机制冲突,在自定义日志处理时更安全;Hyperf\Support\existent()(v3.2.3,PR #7783)与Hyperf\Support\assert_instanceof()(v3.2.4,PR #7792)两个新辅助函数,分别用于存在性判断与类型断言。
废弃代码清理
v3.2.0 与 v3.2.2 分两批清理了历史遗留代码,升级前请搜索业务中是否仍在引用以下 API:
v3.2.0 移除(PR #7610 等):
laminas/laminas-mime包(PR #7278);Hyperf\Serializer\Contract\CacheableSupportsMethodInterface接口(PR #7573);Hyperf\AsyncQueue\JobMessage序列化中的向后兼容代码(PR #7609);- Collection 向后兼容代码、
ProxyTrait参数映射、ResumeExitCoordinatorListener、SocketIO Future 的flag参数、WebSocketHandeShakeException拼写别名等。
v3.2.2 移除(PR #7778):
ConsumerProcess::$queue向后兼容属性(应使用$pool);forceIndexes()(应使用forceIndex());str_replace_once()(应使用strReplaceOnce());ClassLoader::loadDotenv();GrpcClient::hanldeNaming();- watcher 旧配置回退逻辑;
- 废弃的
RuleCollector、Tracer\Adapter\HttpClientFactory、Tracer\Aspect\JsonRpcAspect、ViewEngine\Contract\Enumerable别名。
升级时可借助全局搜索这些标识符,逐一替换为对应新 API 后验证。
修复与行为变更
行为变更(Changed)
hyperf/database中软删除字段deleted_at的默认类型改为datetime(PR #6760),迁移生成的字段类型将与 Laravel 风格对齐;Hyperf\Database\Query\Builder::limit()传入小于零的值时将抛出异常(PR #7208),避免负 limit 引发的隐蔽 SQL 错误;- influxdb 客户端从
influxdb/influxdb-php替换为influxdata/influxdb-client-php(PR #7462),使用 influxdb 统计上报的项目需同步调整客户端调用。
修复(Fixed)要点
- v3.2.0:修复
sortByMany()与sortBy()结果不一致的问题(PR #6934); - v3.2.1:修复
gen:model命令中ModelRewriteInheritanceVisitor无法工作的问题(PR #7760);优化Hyperf\Coordinator\Timer::tick()在Hyperf\Coroutine\wait()内运行回调,确保协程上下文正确(PR #7761); - v3.2.2:修复
ValidatesAttributes::validateMultipleOf无法支持float(PR #7768)、gen:migration-from-database无法工作(PR #7771)、ProcScanHandler无法工作(PR #7774)三个问题; - v3.2.3:修复模型生成时
@property类型错误(如@property int $id→@property ?int $id,PR #7782)、ModelCache\Cacheable与Database\Model\Builder的 phpdoc 问题(PR #7784/PR #7785/PR #7786)、MorphTo关系预加载指定列失效(PR #7788); - v3.2.4:优化 nacos 从实例列表读取 hosts 时对 v1/v2/v3 协议的支持(PR #7790),并修复
StreamHandler在协程并发创建日志目录时的竞态条件(PR #7796)。
优化(Optimized)亮点
Hyperf\Memory\LockManager移除无用参数,validateStartsWith、validateUppercase、validateEndsWith等校验规则改为类型安全、防御式实现(v3.2.5,PR #7779);HasAttributes::isDirty/isClean/wasChanged改用显式可变参数替代func_get_args()(v3.2.5,PR #7803),可读性与静态分析友好度提升;- AMQP 消费者在
concurrent.limit小于qos.prefetch_count时自动扩容并发上限并记录错误日志,避免触发AMQPInvalidFrameException(v3.2.5,PR #7808)——这是高吞吐消息消费场景下非常实用的自我保护机制。
升级行动清单
综合以上变更,从 v3.1 升级到 v3.2 建议按以下顺序执行:
- 环境检查:确认 PHP >= 8.2;若使用 PHP 8.4,全局搜索
fgetcsv/fputcsv调用并补上escape: ''; - 依赖更新:按上文 Dependencies Upgrade 清单升级 composer 依赖,特别注意 Monolog 3.x、symfony ^6||^7、phpunit ^11 等硬性要求;
- 配置迁移:重写 logger 配置 与 cache 配置 为
default + channels/stores新结构; - API 重命名:将所有
getQueueName()改为getPoolName(),ConsumerProcess::$queue改为$pool,同步清理 v3.2.0/v3.2.2 移除的废弃 API; - 行为回归:重点验证 Carbon 时间差计算(
diffInDays绝对值语义)、deleted_at字段类型、limit()负值校验、异步队列路由(dispatch的 pool 回退逻辑)以及 swow 引擎下的响应发射绑定; - 新特性接入:按需开启异步队列消费者自动注册(
enable => true)、使用Pipeline::finally()、NonCoroutine测试属性与assert_instanceof()/existent()等新工具。
本升级指南覆盖了 CHANGELOG-3.2.md 中 v3.2.0 至 v3.2.5 的全部变更条目。由于 v3.2.6 尚在规划(TBD),建议在升级完成后持续关注该文件后续更新,以便第一时间获取 v3.2.6 的变更说明。