17370845950

PHP参数注释仅用于IDE提示、静态分析和文档生成，必须用/* @param 类型 $参数名 /格式写在函数上方DocBlock中，类型与签名须严格一致。

PHP 中参数注释本身没有运行时作用，它只服务于 IDE 提示、静态分析（如 PHPStan、Psalm）和生成文档（如 phpDocumentor），@param 是唯一标准写法，必须写在函数/方法的 DocBlock 里，且紧贴函数声明上方。

参数注释必须写在 DocBlock 里，不能用单行//或#

PHP 解析器完全忽略 @param，只有工具读取 DocBlock（即 /** */ 块注释）里的标签。用 // @param string $name 不会被识别，IDE 不会提示类型，PHPStan 也不会校验。

• ✅ 正确位置：/** @param string $name */ 紧挨着 function 或 public function 上方
• ❌ 错误写法：// @param string $name 或 /* @param string $name */（非 DocBlock 格式）
• ⚠️ 注意：DocBlock 必须是 /** 开头（两个星号），不是 /*

@param 的语法顺序和必填项

格式固定为：@param + 类型 + 参数名 + 可选描述。类型和参数名之间用空格分隔，参数名必须带 $ 符号，否则工具解析失败。

• 基础写法：@param string $name 用户姓名
• 支持联合类型（PHP 8.0+）：@param string|int $id
• 支持数组结构化标注：@param array{name: string, age: int} $user
• 可为空需显式写 |null：@param string|null $email（不要只写 string 然后实际传 null）
• 无描述时也得留空格：@param bool $debug （末尾空格不能省，否则部分工具截断）

常见踩坑：类型写错、漏写$、与实际签名不一致

注释类型和函数定义必须严格对应，否则 IDE 提示错乱、PHPStan 报告假阳性错误。尤其注意：

• 标量类型别名要统一：用 bool 不用 boolean，用 int 不用 integer（虽然都认，但推荐短形式）
• 对象类型写完整类名：@param DateTimeInterface $date，不能只写 @param DateTime（除非已 use）
• 可变参数（...$args）要标成数组：@param array $args
• 如果参数有默认值 = null，注释里仍要写 |null，不能省略

/**
 * 创建用户
 * @param string $name 用户姓名，不能为空
 * @param int|null $age 年龄，可选
 * @param array{role: string, active: bool} $meta 元数据结构
 */
function createUser(string $name, ?
int $age = null, array $meta = []): array
{
    return ['name' => $name];
}

最易被忽略的是「注释类型和实际类型提示（type declaration）同时存在时，两者必须兼容」——比如函数签名写了 string $name，注释就不能写 @param int $name，否则 PHPStan 会直接报错，不是警告。