PHP 8.4 从隐式可空参数迁移类型声明的方法

PHP 8.4 开始弃用“隐式可空参数”：只要参数写成 T $value = null，但类型声明里没有显式包含 null，PHP 在加载这段声明时就会发出弃用提示。普通可选参数通常改成 ?T $value = null 或 T|null $value = null；如果它后面还有必填参数，则应显式可空并移除默认值。

PHP 8.4 弃用说明：https://www.php.net/manual/en/migration84.deprecated.php

对应 RFC：https://wiki.php.net/rfc/deprecate-implicitly-nullable-types

目标和边界：先区分可空与可选

这次迁移的关键不是加一个问号，而是把两个概念拆开：

• 可空：调用方能否显式传入 null，由类型声明 ?T 或 T|null 表达。
• 可选：调用方能否省略参数，由是否存在默认值表达。

旧写法 string $name = null 表面上只声明 string，实际却接受 null。PHP 8.4 的弃用就是要求签名把真实类型写出来。弃用在声明被编译时产生，不需要等函数实际调用。

全流程总览：盘点、分类、改写、回归

推荐迁移顺序是：先在 PHP 8.4 环境以 E_ALL 加载应用和测试，再汇总弃用声明；随后按参数位置和类型结构分类；对接口、抽象类和继承实现成组修改；最后运行静态分析、单元测试和兼容版本测试。

不要只对业务入口做字符串搜索。隐式可空声明可能出现在构造器、接口、Trait、回调签名和供应商扩展点中。依赖注入容器、序列化器和路由器还可能通过反射读取类型，因此“删掉类型”虽然能绕开提示，却会改变工具看到的元数据。

阶段一：普通可选参数直接显式声明 null

如果参数位于末尾，或者它后面的参数也都有默认值，通常只需要把可空性写入类型，保留默认 null。这样调用行为不变：既能省略参数，也能显式传入 null。

?string 与 string|null 在这里表达相同的值域。前者可用于 PHP 7.1 及以上，后者依赖 PHP 8.0 的联合类型。库项目应先看 composer.json 的最低 PHP 版本，再决定统一语法。

阶段二：按签名位置选择迁移方式

最容易误改的是“默认 null 参数后面还有必填参数”的签名。它看似可选，实际上从 PHP 8.1 起省略它会触发 ArgumentCountError。PHP 官方迁移文档要求这种情况移除 = null，保留显式可空类型。

这项修改不会把参数变成不可空；调用方仍能传 null。变化只是签名不再暗示可以省略该位置。迁移时应搜索命名参数调用和反射代码，确认它们没有依赖旧的默认值元数据。

阶段三：联合类型和交集类型分别处理

已有联合类型时，直接把 null 加入联合。交集类型不能写成 ?A&B，应使用 DNF 形式 (A&B)|null。DNF 类型语法需要 PHP 8.2 及以上，因此最低版本较老的库要单独制定兼容方案。

这类声明不要用简单正则批量替换。括号、联合成员去重和最低版本都可能影响语法，优先交给理解 PHP AST 的工具。

阶段四：接口、父类和实现要成组检查

把 T $x = null 改为 ?T $x = null 通常只是把原有运行语义显式化，但继承体系仍要整体检查。接口、抽象方法、父类与子类可能有不同默认值，方法参数还受逆变兼容规则影响。

建议以公共 API 为单位迁移：先改接口和抽象声明，再改实现类，随后运行框架容器编译、代理生成、序列化和反射相关测试。不要为了消除提示直接删除参数类型；这会降低类型安全，并可能改变依赖注入容器或对象填充器的判断。

推荐流程：自动修复只负责改写，测试负责证明

RFC 列出的自动化选择包括 PHP-CS-Fixer 的 nullable_type_declaration_for_default_null_value 规则，以及 PHP_CodeSniffer 搭配 Slevomat Coding Standard 的 NullableTypeForNullDefaultValue 检查；Rector 也可用于 AST 级批量迁移。

1. 在独立分支固定 PHP 最低版本、PHP 8.4 运行版本和依赖锁文件。
2. 开启 E_ALL 执行测试与应用预加载，收集声明级弃用。
3. 先自动修复普通签名，再人工复核“后续有必填参数”、交集类型和继承链。
4. 运行静态分析、单元测试、集成测试与容器编译，检查反射元数据变化。
5. 在最低支持版本和 PHP 8.4 上各跑一次解析与测试，避免引入过新的语法。

常见误区

把默认 null 改成空字符串或 0

这会改变业务语义。迁移目标是显式声明原来已经接受的 null，不是把“未提供”强行映射成另一个值。

所有地方都机械改成 ?T $x = null

如果后面有必填参数，保留默认值会继续触发“可选参数位于必填参数之前”的问题。此时应写 ?T $x，不保留 = null。

忽略供应商代码里的提示

先升级依赖，避免直接修改 vendor。若上游尚未发布兼容版本，应记录补丁或约束版本，并推动上游修复；本地临时改动不能替代依赖治理。

速查表

完成迁移后，类型声明会准确反映参数真实接受的值，默认值只负责可选性。按照“先盘点、再分类、成组改写、双版本回归”的顺序处理，通常能在不修改调用语义的前提下消除 PHP 8.4 弃用，并为 PHP 9 移除隐式行为提前做好准备。