PHP 8联合类型在函数参数和返回值中触发真实运行时检查，值不匹配任一声明类型即抛TypeError，不执行后续逻辑。它强制类型安全，但不替代值校验或业务逻辑判断。
联合类型在函数参数和返回值中的运行时检查机制
PHP 8 的联合类型不是编译期语法糖，而是在每次函数调用或赋值时触发真实运行时类型验证。只要值不属于声明的任一类型，立刻抛出 TypeError，不执行后续逻辑。
常见错误现象包括：
- 传入
[]给声明为int|string的参数 → 报错：TypeError: Argument #1 ($input) must be of type int|string, array given - 从数据库查不到记录却返回
false，但函数声明是User|array→ 同样触发TypeError，而非静默失败
使用场景建议：
- 明确边界：比如 API 响应字段可能为
string或null（string|null），比全用mixed更安全 - 避免隐式转换：
strpos()在 PHP 8.1+ 原生声明为int|false，防止把0当成 false 错误处理 - 不要混用
?和|null：两者等价，但string|null是推荐写法；?string是 PHP 7.1+ 的旧语法，PHP 8 中仍支持但语义不如联合类型清晰
mixed 类型的适用边界与风险点
mixed 等价于 array|bool|callable|int|float|null|object|resource|string，但它不参与联合类型组合 —— mixed|int 是非法语法，PHP 会直接报解析错误。
立即学习“PHP免费学习笔记（深入）”；
它只应在以下情况使用：
- 封装底层扩展调用（如
json_decode($json, $assoc)返回值不确定是array还是object） - 处理遗留代码中完全不可控的输入（例如用户传来的
$_POST深层嵌套结构） - 编写通用工具函数（如日志记录器、序列化桥接层），且你已通过
is_*函数做足运行时校验
容易踩的坑：
- IDE 无法提供补全：声明
mixed $data后，$data->不会提示任何方法 - 静态分析工具（如 PHPStan、Psalm）对
mixed默认放行，等于主动放弃类型防护 - 一旦漏掉
is_array()就直接foreach($data as ...)，运行时崩得毫无预警
联合类型与 null、false 的组合陷阱
PHP 8.0 开始允许 null 显式出现在联合类型中，但必须写全：string|null 合法，?string 虽兼容但不推荐用于新代码；int|?string 是语法错误。
PHP 8.1 新增 false 支持，专为传统函数设计：
-
file_get_contents(string $filename): string|false—— 明确区分「读取成功」和「失败」两种语义 -
in_array(mixed $needle, array $haystack): bool|int是错的，因为in_array实际返回bool，不能写成bool|int - 注意
false和0/''的区别：联合类型只校验类型，不校验值，0属于int，哪怕函数本意是「没找到」
性能影响极小，但类型声明越精确，OPcache 预编译优化效果越稳定 —— 尤其在 JIT 开启时，类型信息能帮助生成更优机器码。
什么时候该用联合类型，而不是 mixed？
判断标准很简单：你能列出所有可能的类型，并且数量 ≤ 4。
例如：
- 数据库 ID 字段：可能是
int（自增）、string（UUID）、null（未保存）→ 用int|string|null - 缓存读取结果：可能是
string（命中）、bool（未命中）、null（空值缓存）→string|bool|null合理 - 但一个 HTTP 请求的完整响应体：可能含
string（文本）、array（JSON 解析后）、resource（流）、object（Guzzle Response 对象）→ 此时应拆分接口，或用mixed+ 显式instanceof分支，而非硬塞进联合类型
最易被忽略的一点：联合类型声明本身不会改变值的行为，它只是加了一道门禁。门禁开了之后，你依然要自己检查 $input 到底是 int 还是 string，才能决定走哪条分支逻辑 —— 类型系统不替你写业务判断。
