PHP 8.2联合类型迁移核心目标是保障代码在新版本下通过类型检查、运行稳定，并为严格类型演进奠基，关键动作包括识别伪联合类型、替换签名、统一返回声明及处理null安全性。
明确联合类型改造的核心目标
PHP 8.2 原生支持联合类型（Union Types），而 PHP 7.4 仅支持类名、数组、callable 等有限类型声明，且不支持 | 语法。迁移重点不是“把所有类型都改成联合类型”，而是让代码在 PHP 8.2 下能通过类型检查、运行稳定，并为后续严格类型演进打基础。关键动作包括：识别 PHP 7.4 中的“伪联合类型”写法（如注释中的 @param string|int）、替换函数签名、统一返回值声明、处理 null 安全性（尤其与 ?T 可空类型的交互）。
自动化扫描 + 人工校验双轨识别
先用静态分析工具定位待改点，再人工确认语义合理性：
- 用 PHPStan（level 5+）或 Psalm（
--php-version=8.2）扫描 PHP 7.4 代码，聚焦报错中含type mismatch、invalid union、nullable相关提示的函数/方法 - 搜索项目中所有
@param/@return含|的 PHPDoc（如@param int|string $id），这些是联合类型的高概率候选区 - 重点关注参数含默认值为
null的方法（如function foo($x = null)），它们常需改为function foo(?string $x = null)或function foo(string|null $x = null) - 过滤掉明显属于“历史兼容写法”的地方（如框架 Hook 回调、第三方 SDK 封装层），优先保障业务核心域逻辑
分层改造策略：接口 → 实现 → 调用链
避免全局替换引发连锁编译失败，按依赖方向推进：
-
第一层：定义契约 —— 先修改
interface和abstract class中的方法签名，强制子类/实现类对齐。例如将public function getId(): string;改为public function getId(): int|string; -
第二层：落地实现 —— 修改具体类中对应方法，同步更新
return值类型、内部变量类型断言（必要时加is_int()/is_string()校验） -
第三层：调用方适配 —— 检查所有调用该方法的地方，若原调用假设返回恒为
string，则需补match或gettype()分支处理；对传参处，确保传入值满足新联合类型约束（如不能传float给int|string参数） - 对 DNF（Do Not Fix）场景（如遗留支付回调入口、日志埋点等低变更价值模块），用
#[\ReturnTypeWillChange]或@phpstan-ignore-next-line显式标注，留待二期重构
构建可验证的迁移质量门禁
光改完代码不够，必须嵌入 CI 流程保障长期一致性：
立即学习“PHP免费学习笔记（深入）”；
- 在
phpstan.neon中启用phpVersion: 8.2，并开启strict-rules扩展，禁止未声明联合类型的隐式混合类型 - 新增 PHPUnit 数据提供器（
@dataProvider），为每个改造后的联合类型方法覆盖各类型分支的单元测试（如int输入、string输入、null输入） - 用 PHP-CS-Fixer 配置
union_operator_spaces和nullable_type_declaration_for_default_null_value规则，统一代码风格 - 在部署前加入
php -l+php --syntax-check双重校验，拦截因|位置错误（如空格缺失）导致的解析失败
string|int 是表示 ID 的两种编码格式？还是历史数据兼容？这决定了你是否该引入 Value Object 封装，而非简单加联合类型。 
