PHP8怎么用联合类型声明参数-php教程-PHP中文网

php 8.0起原生支持联合类型，用竖线|分隔多个类型，适用于函数参数、返回值和类属性；运行时校验是否匹配任一类型，支持int|string、string|null等组合，不支持void参与，?string等价于string|null。

php8怎么用联合类型声明参数

PHP 8.0 起原生支持联合类型（Union Types），直接用竖线 | 分隔多个类型，适用于函数参数、返回值和静态变量——这是最核心、最常用的支持场景。

函数参数中使用联合类型

语法简洁明确，PHP 运行时会自动校验传入值是否属于声明中的任一类型（启用 strict_types=1 时更严格）：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

<?php declare(strict_types=1);

function logId(int|string $id): void
{
    echo "ID: " . $id . "\n";
}

logId(42);      // ✅ 合法：int
logId("abc");   // ✅ 合法：string
logId([]);       // ❌ TypeError：array 不在 int|string 中

支持的类型包括：int、string、float、bool、array、object、callable、iterable、类名（如 DateTime）、接口名，以及 null（但不能单独用 void 或与其他类型混用）。
null 必须显式写进联合类型，例如 string|null；?string 是它的等价简写，语义完全一致。

常见合法组合示例

int|float：接受整数或浮点数（数值计算常用）
string|null：表示字段可能为空（API 响应、数据库查询结果）
array|Traversable：兼容数组和迭代器对象
User|Guest：自定义类之间的多态输入
string|int|bool：需谨慎，避免隐式转换歧义（比如 true → 1）

注意事项与避坑点

不能用 void 参与联合：void|int 是非法语法，void 只能单独作返回类型。
类型顺序无关语义，但建议把高频类型放前面（如 string|int 比 int|string 更符合读写习惯）。
不支持运行时自动类型转换：传入 "123" 给 int 参数会报错，即使它可转为整数；联合类型只做“值类型匹配”，不做强制转换。
IDE 和静态分析工具（如 PHPStan）能基于联合类型做深度检查，比如发现 $id = [] 赋值给 int|string $id 参数会被标记为错误。

和 PHP 7.4 的对比

场景	PHP 7.4	PHP 8.0+
参数允许多类型	仅靠 `@param int\|string` 注释	原生 `int\|string $id` 语法支持
类型错误时机	运行时手动 `is_int()` 判断	严格模式下，调用时直接抛 `TypeError`