PHP怎么注释返回值_PHP返回值注释法【明确】_技术教程

PHP中用@return注释声明返回值类型，需置于函数上方DocBlock内，格式为@return 类型说明，类型大小写敏感、联合类型用|连接，void与null不可混用，且须与PHP 8+返回类型声明兼容。

PHP里怎么给函数写返回值注释

PHP本身不强制检查返回值类型，但用@return注释能被IDE识别、生成文档、配合静态分析工具（如PHPStan、Psalm）做类型校验。关键不是“能不能写”，而是“写对格式IDE才认”。

必须放在函数声明上方的DocBlock里，且紧贴函数，中间不能空行
@return后面要跟类型，再跟可选说明（如@return string 用户昵称，空字符串表示未设置）
类型名大小写敏感：用string，别写String；bool不是boolean（后者虽常见但部分工具不认）
联合类型用|分隔，如@return int|false（注意无空格）
泛型写法暂不被原生支持，需用@return array这类伪泛型（PHPStan 1.10+ 支持array语法）

什么时候必须写`@return`注释

不是所有函数都得写，但以下场景不写就容易出问题：

函数可能返回null或false（比如fopen()失败返回false），不注明IDE无法提示你判空
返回数组但结构固定（如['id' => 123, 'name' => 'foo']），可用@return array{id: int, name: string}（PHPStan支持）
返回对象实例，且调用方会链式调用（如getUser()->getEmail()），不写@return User，IDE点不到getEmail()
使用了PHP 8.0+的返回类型声明（如function foo(): ?string），仍建议补@return——因为注释可比类型声明更细（比如说明“仅当缓存命中时返回非null”）

`@return void`和`@return null`的区别

这是最容易混淆的一对。PHP中void表示“不返回任何值”，null是实际返回了一个null值。

函数没写return，或只写return; → 正确注释是@return void
函数明确return null; → 应写@return null，或更常用@return ?string（如果本该返回string）
写成@return void却实际返回null，PHPStan会报错：Function xxx() has no return statement, but return type is void
写成@return null但函数真没return语句，也会触发警告

/**
 * 根据ID查用户，查不到返回null
 * @param int $id
 * @return User|null
 */
function findUser(int $id): ?User {
    $row = db_query("SELECT * FROM users WHERE id = ?", [$id]);
    return $row ? new User($row) : null;
}