PHP 联合类型声明

wen PHP项目 2026-08-10 2

本文目录导读：

PHP 联合类型声明

目录导读
什么是 PHP 联合类型声明？
联合类型声明的语法与基础用法
为什么需要联合类型？——解决的实际痛点
联合类型与空值（null）的优雅处理
联合类型在继承与接口中的规则（协变与逆变）
严格类型模式下的联合类型行为
实战案例：用联合类型重构遗留代码
常见误区与最佳实践
问答环节（FAQ）
总结与展望

PHP 联合类型声明：从入门到精通，提升代码健壮性的现代实践**

目录导读

什么是 PHP 联合类型声明？
联合类型声明的语法与基础用法
为什么需要联合类型？——解决的实际痛点
联合类型与空值（null）的优雅处理
联合类型在继承与接口中的规则（协变与逆变）
严格类型模式下的联合类型行为
实战案例：用联合类型重构遗留代码
常见误区与最佳实践
问答环节（FAQ）
总结与展望

什么是 PHP 联合类型声明？

PHP 在 8.0 版本中正式引入了联合类型（Union Types），这是一种类型声明机制，允许一个参数、返回值或属性接受两种或多种指定类型中的任意一种，在此之前，PHP 开发者往往只能通过 PHPDoc 注解或者 mixed 类型来模糊处理，而联合类型将这种“模糊”提升为了语言级的内置规范。

你有一个函数需要接收一个“数字”，它既可以是整数 int，也可以是浮点数 float，过去你可能会写 mixed 或者不写类型，现在你可以明确声明为 int|float。

联合类型声明的语法与基础用法

语法非常直观,使用竖线分隔多个类型，它可以用在三个位置：

函数/方法参数

function calculateArea(int|float $radius): int|float {
    return pi() * $radius * $radius;
}

函数/方法返回值

function findUser(int $id): User|null { // 等价于 ?User
    // ...
}

类属性（PHP 8.4 起支持，但 8.0 起可对属性进行类型声明）

class Order {
    public int|string $orderId; // 可以是数字ID或字符串编号
}

关键点：联合类型中的每个类型必须唯一，不能重复（如 int|int 会报错）。

为什么需要联合类型？——解决的实际痛点

在没有联合类型之前,处理“多类型”场景通常有两种方式：

使用 mixed：这等于放弃了静态分析能力，任何错误赋值在运行时才会暴露，IDE 也无法提示。
依赖 PHPDoc：@param int|float $value，但这只是注释，PHP 引擎本身并不强制执行，容易产生注释与代码不一致的“幻觉文档”。

痛点对比：

场景	旧方案（PHPDoc）	新方案（联合类型）
参数校验	需要手动 `is_int()` 或 `is_float()` 判断	引擎自动强制类型，不符直接抛 `TypeError`
IDE 提示	仅提示为“混合”，无法自动补全	全类型智能补全，支持方法链
重构安全	改一处类型需全局搜索注释	编译期检查，错误即暴露

联合类型与空值（null）的优雅处理

这是最常见的场景,过去两个写法等价：

// 旧写法：可空类型
function getConfig(?string $key): ?string { ... }
// 新写法：显式联合
function getConfig(string|null $key): string|null { ... }

实质性区别：
联合类型 string|null 比 ?string 表达力更强，因为未来如果支持 true 或 false 作为类型（PHP 8.2 引入），你可以写出 true|false|null 这种非常语义化的声明，而符号只能修饰一个类型。建议：在新代码中统一使用 |null，提高可读性。

联合类型在继承与接口中的规则（协变与逆变）

这是初学者最头疼的部分,但规则其实很简单：

返回类型（协变）：子类方法的返回类型只能缩小（更具体），不能扩大。
例如父类返回 Animal|Dog，子类可以返回 Dog（因为 Dog 是 Animal|Dog 的子集），但绝不可以返回 Animal|Cat|Dog。
参数类型（逆变）：子类方法的参数类型只能放大（更宽泛），不能缩小。
例如父类参数要求 Cat，子类可以放宽为 Animal|Cat，但不可以收紧为 SpecificCat。

案例：

interface Parser {
    public function parse(string|array $data): array;
}
class JsonParser implements Parser {
    // 合法：参数放大了（加了 int），返回类型不变
    public function parse(string|array|int $data): array { ... }
}

严格类型模式下的联合类型行为

在文件开头声明 declare(strict_types=1); 后，联合类型的强制转换行为会发生变化：

非严格模式：int|float 参数传入字符串 "10" 会被自动转换成整数 10（弱校验）。
严格模式："10" 作为字符串传入 int|float 参数会直接抛 TypeError，因为字符串既不是 int 也不是 float。

特别注意：联合类型不支持 mixed 作为其中一项（因为 mixed 本身包含所有类型，联合无意义），也不支持 void 参与联合（void 本身就是无返回的意思）。

实战案例：用联合类型重构遗留代码

遗留代码：

/**
 * @param $id 可以是数字ID或者UUID字符串
 * @return User
 */
function getUser($id) {
    if (!is_int($id) && !is_string($id)) {
        throw new InvalidArgumentException('ID must be int or string');
    }
    // ... 查询逻辑
}

重构后：

function getUser(int|string $id): User {
    // 无需手动校验，类型错误自动抛出 TypeError
    // 查询逻辑...
}

效果：删除了 4 行校验代码，IDE 能识别 $id 是数字或字符串，$id-> 不再报错（因为 int 和 string 都没有方法，但至少不会乱提示）。

常见误区与最佳实践

将联合类型当作“万能类型”滥用

// ❌ 错：明明可以设计一个基类或接口
function process(int|string|array|object $data) { ... }

如果类型超过 3 个，请考虑抽象为“实体类”或“DTO”，联合类型是为了解决“小范围选择”，而非设计上的“妥协”。

忘记复合类型的歧义
array|ArrayObject 这种联合，虽然合法，但建议统一为标准数组，减少心智负担。

最佳实践清单：

✅ 优先使用 int|float、string|int 这类标量组合。
✅ 对于 null，统一写 |null，不要混用。
✅ 在接口设计时，尽量让联合类型“窄”，保持接口稳定。
✅ 总是开启 strict_types=1，避免隐式转换掩盖 bug。

问答环节（FAQ）

Q2：联合类型支持 iterable 或 callable 吗？
支持，你可以声明 iterable|array（通常冗余，因为 iterable 已包含 array），或者 callable|string（用于回调函数名或闭包）。

Q3：联合类型能用于常量声明吗？
不能，常量只能有单一类型，这是赋值语义决定的。

Q4：如何判断一个值是否属于联合类型中的某一项？
用 get_debug_type() 函数（PHP 8.0+），返回精确的字符串类型名，配合 in_array() 判断。

总结与展望

PHP 联合类型声明是语言走向强类型、可静态分析的重要里程碑，它不仅减少了代码中的防御性校验，还让 IDE 的智能提示更加精准——这是 PHP 8.x 系列最实用、最具性价比的特性之一，尤其适合中大型项目的长期维护。

行动建议：从今天开始，对你新写的函数和类，把 mixed 和 ?Type 替换为具体的联合类型，你会立刻感受到代码自文档化和错误前置捕获带来的舒适感，随着 PHP 8.4 对属性类型和钩子（hooks）的增强，联合类型将更深度地融入 OOP 设计，是你走向现代 PHP 开发的必备技能。

（注：本文所有代码示例均基于 PHP 8.0 及以上版本，实际运行请确保环境符合要求。）