前言PHP 8.0 引入联合类型Union Types之后很多人产生了一个误会以为 PHP 终于有泛型Generics了于是写出function wrap(T $item): T这样的签名等着运行时给个明确报错结果要么类型检查永远通不过要么报错信息里冒出一个莫名其妙的类名。误会的原因在于联合类型和泛型解决的是两个完全不同的问题。联合类型回答的是这个位置可以是哪几种类型中的一种比如int|string泛型回答的是这个容器里的元素是什么类型比如一个装User的列表。PHP 8.0 给的是前者PHP 至今没有语言级的泛型——T这类类型参数在 PHP 里不是关键字运行时不认识它。那结合使用到底指什么指的是这套组合拳用 PHP 的语言特性联合类型、mixed、交叉类型、DNF 类型把能在运行时检查的部分表达出来用 PHPDoc 把运行时表达不出来的泛型信息标注出来再交给静态分析工具PHPStan 或 Psalm在分析期检查。前者是硬的后者是软的两者拼起来才接近有泛型的效果。本文从概念区分讲起说明联合类型的语义边界然后给出把两者接起来的实际写法最后是一份能直接运行的完整示例和几个常踩的坑。一、把两类东西分清楚这张表是全文的基础先把它记住后面很多困惑会自动消失。写法属于什么引入版本谁来检查int\string语言级联合类型PHP 8.0?int即 int\null语言级可空类型PHP 7.1mixed语言级类型PHP 8.0运行时几乎不做限制AB交叉类型语言级交叉类型PHP 8.1运行时(AB)\C DNF 类型语言级组合类型PHP 8.2template T、T[]PHPDoc 文档标注工具约定不是语言特性PHPStan / Psalm 静态分析array{id: int}PHPDoc 数组形状工具约定静态分析关键差别只有一句上表后两行删掉代码照样能跑前三行删掉运行时的类型检查就没了。所以泛型注解的价值完全建立在你确实跑了静态分析这个前提上——不跑静态分析工具template T只是一句注释。二、联合类型的语义边界写联合类型时有几条硬规则违反它们得到的是编译期致命错误脚本一行都不会执行。?php // 需要 PHP 8.0 // ❌ 重复类型编译期致命错误提示 Duplicate type int is redundant // function a(int|int $v): void {} // ❌ 与 mixed 组合mixed 已经包含所有类型不能并列书写 // function b(mixed|int $v): void {} // ❌ void 不能出现在联合类型里 // function c(): void|false {} // ✅ 正确的几种写法 function d(int|string $v): string { return is_int($v) ? (string) $v : $v; } function e(int|false $v): bool // false 从 PHP 8.0 起可以作为独立类型使用 { return $v ! false; } function f(?string $v): string // ?string 就是 string|null { return $v ?? ; } var_dump(d(1), d(a), e(false), f(null));另外要记住一个等价关系iterable等价于array|Traversable所以array|iterable这种写法会因为重复而被判为冗余。同理bool等价于true|false在 PHP 8.2 之后true才成为可独立书写的类型如果同时写bool|false也会报冗余。三、把泛型信息接上去T 不能出现在真实类型里这是全文最重要的一条实践结论template声明的T只能出现在 PHPDoc 里绝对不能直接写进 PHP 的参数或返回类型声明。原因很直接PHP 解析类型声明时看到T会把它当成一个类名。类名在运行时才解析所以你不会在编译期得到这不是个类型参数的提示而是会在某个时刻碰到两种结果之一类型检查永远匹配不上或者报错说找不到这个类。两种情况都很难排查。正确做法是真实类型退到mixed或联合类型精确类型写进 PHPDoc。?php // 需要 PHP 8.0 declare(strict_types1); /** * 一个带类型标注的列表容器 * * template T */ final class TypedList { /** var T[] */ private array $items []; /** * param T $item */ public function add(mixed $item): void // 真实类型只能是 mixed { $this-items[] $item; } /** * return T|null */ public function first(): mixed // 同样退到 mixed { return $this-items[0] ?? null; } /** * return T[] */ public function all(): array { return $this-items; } public function count(): int { return count($this-items); } } $users new TypedList(); $users-add(tom); $users-add(jerry); var_dump($users-count()); // int(2) var_dump($users-first()); // string(3) tom关于某个具体类的通用容器这类注解PHPDoc 的标准写法是在类型名后面用尖括号标注类型参数本文的示例统一改用T[]这种形式静态分析器对两者的理解是一致的。3.1 用 T 约束联合类型的语义泛型真正发力的地方是当你需要表达输入和输出的元素类型相同时。联合类型本身表达不了这种关联泛型可以?php // 需要 PHP 8.0 declare(strict_types1); /** * 把输入统一成数组传入单个值得到单元素数组传入数组原样返回 * * template T * param T|T[] $input * return T[] */ function normalize(mixed $input): array { return is_array($input) ? array_values($input) : [$input]; } var_dump(normalize(5)); // [5] var_dump(normalize([1, 2, 3])); // [1, 2, 3]T|T[]这个注解是联合类型和泛型配合的最典型形态联合类型负责可以是单个也可以是多个这个形状泛型负责这两处的元素是同一个类型这个约束。静态分析器据此能同时发现两类错误——传了不该传的类型或者接收方按错误的元素类型使用结果。3.2 给类型参数加约束泛型不加约束会退化成mixed失去检查意义。PHPDoc 用of关键字给类型参数限定范围?php // 需要 PHP 8.0 declare(strict_types1); /** * template T of \DateTimeInterface * param T $a * param T $b * return T */ function later(mixed $a, mixed $b): mixed { return $a-getTimestamp() $b-getTimestamp() ? $a : $b; } var_dump(later(new DateTime(2026-01-01), new DateTime(2026-06-01))-format(Y-m-d));有了of \DateTimeInterface这个约束静态分析器就知道函数体里调用getTimestamp()是安全的同时会拒绝传入字符串。3.3 PHP 8.2 的 DNF 类型让联合与交叉结合如果你的项目能用到 PHP 8.2DNF 类型Disjunctive Normal Form Types可以让联合里嵌套交叉表达能力更进一步?php // 需要 PHP 8.2 declare(strict_types1); /** * 接受既可计数又能当数组访问的对象或者直接给 null */ function describe((CountableArrayAccess)|null $box): string { if ($box null) { return empty; } return count . count($box); } var_dump(describe(null)); // emptyDNF 类型是运行时真实生效的检查不需要静态分析器参与——这是它和泛型注解的本质区别能用语言表达的就不要只写在注释里。所以判断标准很简单如果某个约束能用联合类型、交叉类型、DNF 类型表达就用语言特性只有当约束涉及元素类型的一致性这种运行时无法表达的语义时才退到 PHPDoc 泛型。代码实战一份完整可运行的示例把下面这段保存成generics_demo.php直接运行它把联合类型、mixed、PHPDoc 泛型、数组形状注解放在一起使用输出的是真实结果。?php // 需要 PHP 8.0保存后执行php generics_demo.php declare(strict_types1); /** * 通用结果包装成功时携带数据失败时携带错误信息 * * template T */ final class Result { /** * param T|null $value */ private function __construct( public bool $ok, private mixed $value, private string $error ) { } /** * 创建成功结果 * * template U * param U $value * return self */ public static function ok(mixed $value): self { return new self(true, $value); } /** * 创建失败结果 * * return self */ public static function fail(string $error): self { return new self(false, null, $error); } /** * 联合类型在这里派上用场取值可能成功也可能拿到错误信息 * * return T|null */ public function value(): mixed { return $this-ok ? $this-value : null; } public function error(): string { return $this-error; } } /** * param array{id: int, name: string} $row * return Result */ function greet(array $row): Result { if ($row[name] ) { return Result::fail(缺少 name 字段); } return Result::ok(hello, . $row[name]); } $r1 greet([id 1, name tom]); $r2 greet([id 2, name ]); foreach ([$r1, $r2] as $i $r) { if ($r-ok) { printf(#%d ok, value%s\n, $i, var_export($r-value(), true)); } else { printf(#%d 失败, error%s\n, $i, $r-error()); } }运行结果#0 ok, valuehello, tom #1 失败, error缺少 name 字段要让泛型注解真正产生价值需要装上静态分析工具并让它跑起来# 在项目里安装 PHPStan开发依赖 composer require --dev phpstan/phpstan # 分析源码级别越高检查越严格 vendor/bin/phpstan analyse src --level6分析器会把Result::ok(123)之类的调用与上一节声明的返回类型注解逐项比对在不运行代码的情况下指出类型不一致。这也是泛型注解唯一的收益来源它不能防止运行时错误只能提前把不一致暴露在开发阶段。常见坑点1. 以为联合类型就是泛型❌function wrap(int|string $v)之后宣称PHP 8.0 支持泛型了✅ 联合类型表达几种类型之一泛型表达容器元素的类型。PHP 至今没有语言级泛型泛型只能靠 PHPDoc 加静态分析工具2. 把 T 写进真实的类型声明❌public function add(T $item): T {}—— PHP 会把T当成类名解析✅ 真实类型写mixedPHP 8.0 起可用或联合类型把param T写进 PHPDoc3. 写了泛型注解却从不跑静态分析❌ 项目里template写得满满当当CI 里没有任何分析步骤✅ 注解与工具是一对缺一半等于没有。把phpstan analyse加进 CI并给一个明确的级别目标4. 联合类型里写重复类型❌int|int、mixed|string、array|iterable—— 编译期致命错误✅ 记住等价关系iterable就是array|Traversablemixed已经包含一切bool包含true与false5. 可空写法叠用❌?int|null这类写法会被判定为类型重复✅ 二选一用?int或者写int|null6. 用泛型注解代替输入校验❌ 认为param int $id能挡住外部传进来的字符串✅ PHPDoc 不参与运行时。来自请求的参数仍然要显式校验和类型转换7. 忘了never的语义❌ 在联合类型里写never或者在返回never的函数里写了return;✅never是 PHP 8.1 引入的返回类型表示函数永不正常返回总是抛异常或退出它不能出现在联合类型里8. 类型注解与实现各写一套❌ PHPDoc 写return string[]实际函数在某些分支返回null✅ 注解要和实现一致不一致时静态分析器会报错别把报错当成工具太严关掉总结需求用什么表达生效时机一个参数可以是几种类型之一联合类型 int\stringPHP 8.0一个对象必须同时满足多个接口交叉类型ABPHP 8.1运行时联合里嵌套交叉DNF 类型 (AB)\CPHP 8.2容器里的元素类型PHPDoctemplate T与T[]静态分析期输入与输出的元素类型一致param T\T[]与return T[]限制类型参数的范围template T of SomeInterface静态分析期联合类型和泛型结合使用在实践中就是一条分界线能用语言特性表达的约束全部用联合类型、交叉类型、DNF 类型写出来让运行时把关只有元素类型一致性这类运行时表达不了的语义才退到 PHPDoc 泛型注解由静态分析器把关。记住T不能出现在真实类型声明里、泛型注解必须配静态分析工具这两点就不会在这条路上走弯路。