PHP怎么注释类_PHP类注释规则【必知】

2026-01-16

PHP怎么注释类_PHP类注释规则【必知】

PHP类注释必须使用标准PHPDoc格式（/* /），正确标注@param、@return、@property、@method等标签，否则影响IDE补全、静态分析和文档生成。

php怎么注释类_php类注释规则【必知】

PHP 类注释不是可有可无的装饰，而是 IDE 补全、PHPStan/ Psalm 静态分析、生成文档（如 phpDocumentor）的前提。没写对 @param 或漏掉 @return，phpstan 就可能报错，PhpStorm 也识别不出返回类型。

类声明上方必须用 PHPDoc 块注释

不能用单行 // 或多行 /* */ 替代。只有以 /** 开头、每行以 * 对齐、以 */ 结尾的块，才会被解析为 PHPDoc。

错误写法：

/* 这是普通注释，不会被解析 */
class UserService {}

正确写法：

/** 
 * 用户服务类，负责用户注册、登录和信息更新
 */
class UserService {}

@package 和 @author 不强制，但团队协作中建议统一加 @package（如 @package App/Services），方便后续生成文档结构

@property 和 @method 必须写在类级 PHPDoc 中

这两个标签只在类声明正上方的 PHPDoc 块里生效，用于描述“魔术属性”或“动态方法”，比如 Laravel 的 Eloquent 模型或使用 __get/__call 的类。

@property 告诉 IDE 和静态分析器：这个类虽无真实属性，但能读写 $user->name
```
/** 
 * @property string $name
 * @property int $age
 */
class User { ... }
```
@method 用于声明动态方法签名，否则调用 $user->scopeActive()->get() 时 IDE 会标红
```
/** 
 * @method static User query()
 * @method User active()
 */
class User extends Model {}
```
注意：这些标签不改变运行时行为，只是“告诉工具该这么理解”，写错类型（如把 @property int $id 写成 @property string $id）会导致 IDE 提示错误或静态分析误报

构造函数参数必须用 @param 显式标注

PHP 8+ 支持构造函数属性提升（public function __construct(public string $name)），但即使如此，仍需在类级 PHPDoc 中用 @param 描述每个参数——因为 PHPDoc 是给开发者和工具看的，不是给 PHP 解析器看的。

酷表ChatExcel

北大团队开发的通过聊天来操作Excel表格的AI工具

下载

立即学习“PHP免费学习笔记（深入）”；

哪怕用了属性提升，也要补全：

/** 
 * @param string $name 用户姓名
 * @param int $level 权限等级，默认 1
 */
class User {
    public function __construct(
        public string $name,
        public int $level = 1
    ) {}
}

如果参数是联合类型（如 string|null），@param 必须写全：@param string|null $email，不能简写为 @param string $email
PHP 8.0+ 的 mixed 类型要显式写 @param mixed $data，否则部分工具（如 PHPStan level 6+）会警告“缺少类型信息”

最常被忽略的是：类注释里的 @return 是留给静态方法的，不是给类本身用的；而 @var 只能用于变量赋值行上方，不能放在类 PHPDoc 里。混淆这些位置，注释就彻底失效了。

https://www.php.cn/faq/1991074.html