PHP返回值类型声明规范完整指南及代码示例

数码系统

相机 win10

测评 win11

手机智车

华为 Tesla

小米理想

苹果蔚来

游戏软件

LOL 抖音

原神微信

当前位置：首页

编程语言

PHP返回值类型声明规范完整指南及代码示例

热心网友时间：2026-07-14

转载

PHP返回值类型声明规范：使用冒号加类型名，基础类型小写如`int`、`string`；可空`?Type`与`void`语义不同；严格模式需`declare(strict_types=1)`，仅对当前文件生效；PHP8+支持联合类型（如`int|string`），`resource`不可用。

在PHP开发中，返回值类型声明不仅是语法糖，更是提升代码健壮性与可读性的关键利器。正确运用这一规范，能够显著增强函数逻辑的清晰度。其核心规则十分直观：在函数参数列表的右括号之后、函数体左花括号之前，使用冒号（:）后接所期望的返回类型名称即可。

然而，一个极易被忽视的前提是：必须搭配 declare(strict_types=1); 指令，才能激活严格的运行时类型校验。若不启用，PHP仅将其视为“意图提示”，弱类型转换依然会悄然发生，从而埋下难以追踪的bug隐患。

基础类型声明须使用小写短名

PHP对于标量类型的声明有着独特的规则——只认可标准的小写形式，如 int、string、bool、float、array 和 void。若尝试使用 Integer 或 Boolean 等大写形式，语法上虽不会报错，但解析器会静默将其转换为小写，导致IDE提示与错误信息与实际代码不一致，增加排查成本，得不偿失。

function getId(): int { return 42; } ✅ 这才是符合规范的写法
function getName(): String { return 'abc'; } ❌ 这种写法不合规，String 并非有效类型
function getConfig(): array { return ['host' => 'localhost']; } ✅ 这是声明数组返回值的唯一正确方式，切勿使用 [] 或 Array 替代。

可空类型与 void 的语义切勿混淆

自 PHP 7.1 起，可空类型（?Type）被引入，表示“返回该类型或 null”。语法上等价于 Type|null。

但需特别警惕：?Type 与 void 的语义截然不同。void 意味着函数执行完毕后不返回任何可用值。若试图用 $res = sa veLog('msg'); 接收 void 函数的返回值，PHP 将直接抛出致命错误。

function findUser(int $id): ?User { return $id === 1 ? new User() : null; } ✅ 要么返回 User 对象，要么返回 null，逻辑清晰合理。
function log(string $msg): void { error_log($msg); } ✅ 记录日志无需返回值，使用 void 最为恰当。
function log(string $msg): void { return 'done'; } ❌ 致命错误！既然声明了 void，就不能返回任何内容。
function delete(int $id): void { return $id > 0; } ❌ 典型的语义错误。若删除操作结果需要被调用方感知，应返回 bool 类型，而非用 void 掩盖结果。

strict_types=1 仅作用于当前文件

启用严格模式（declare(strict_types=1);）后，当前文件内定义的所有函数，其参数和返回值均会进行精确类型匹配。一旦类型不匹配，PHP 会立即抛出 TypeError 异常，而非静默转换。

一个常见陷阱是：strict_types 声明不会跨文件传播。假设在 A.php 中开启了严格模式，并通过 require 'B.php' 引入另一文件。若 B.php 自身未声明严格模式，则 B.php 中的函数仍按弱类型模式运行。

未开启严格模式：function foo(): int { return "123"; } → 一切正常，PHP 将字符串 "123" 静默转换为整数 123。
开启严格模式：function foo(): int { return "123"; } → 立即报错：Return value must be of type int, string returned。
PHP 8+ 特别提醒：若函数体某个分支遗漏了 return 语句，函数末尾会隐式返回 null。在严格模式下，这同样会触发 TypeError。而 PHP 7.x 则会静默将 null 转为 0，这种隐蔽的逻辑漏洞一旦上线，排查极为棘手。

联合类型与自定义类型需版本对齐

使用 PHP 8.0 及以上版本时，可通过竖线 | 声明联合类型，例如 int|string|float，使函数签名更加灵活。对于类名，务必使用完整的命名空间，如 DateTime。此外，iterable、callable、object 等复合类型同样受支持。

特别提醒：相对类类型（self、parent、static）仅能在类方法内部使用，应用于普通函数时会报错。

function formatId(mixed $id): int|string { return is_numeric($id) ? (int)$id : (string)$id; } ✅ 这是 PHP 8.0+ 的灵活写法。
function now(): DateTime { return new DateTime(); } ✅ 使用完整命名空间是标准做法。
class User { public function clone(): static { return new static(); } } ✅ static 作为返回类型声明，常用于实现返回调用者自身的链式调用模式。
function handle(): resource { ... } ❌ 注意，resource 类型不被允许作为返回类型声明，这一点容易被忽略。