PHP编程PHPDoc怎么学_PHPPHPDoc编程学习【教程】-php教程-PHP中文网

phpdoc注释必须用/* /格式，紧贴函数声明上方无空行，否则ide和静态分析工具无法识别；@param和@return类型须与签名严格一致并覆盖所有分支，如user|null而非仅user。

php编程phpdoc怎么学_phpphpdoc编程学习【教程】

@param 和 @return 不是装饰器，也不是运行时生效的语法——它们只是注释，但 IDE、静态分析器（如 PHPStan）、文档生成器（如 phpDocumentor）会读取它们。学 PHPDoc 的核心不是“背标签”，而是理解「在哪写、写什么、为什么这行注释能被工具识别」。

PHPDoc 注释块必须严格用 `/** */` 包裹

很多新手写成 /* */ 或 //，结果 PHPStan 报告“未声明参数类型”，IDE 也不提示。只有以 /** 开头、*/ 结尾的块，才会被认定为 DocBlock。

常见错误现象：

写了 /* @param string $name */ → 工具完全忽略
写了 /// @param string $name → 不是标准格式，不解析
在函数体内写 DocBlock（比如放在 if 后面）→ 位置错，关联不上函数

正确位置：紧贴在函数、方法、类、属性声明的正上方，中间不能空行。

示例：

/**
 * 格式化用户姓名
 * @param string $name 姓名，不能为空
 * @return string 带前缀的姓名
 */
function formatUserName(string $name): string { ... }

`@param` 类型要和实际参数声明一致，否则产生误导

PHP 8+ 支持原生类型声明，@param 应该与之对齐，而不是“写得更宽泛”。比如函数签名是 int $id，就别写 @param mixed $id。

参数差异带来的影响：

写 @param int|string $id 但函数只接受 int → PHPStan 会报类型不匹配
漏写可为空标记，比如实际是 ?string $desc，却写 @param string $desc → IDE 提示可能为 null 时无预警
用 @param array<string int></string> 描述关联数组，比 @param array $data 更利于静态分析

建议优先使用 PHP 原生类型（string、bool、array），复杂结构用泛型语法（PHP 8.1+ 支持）或 list/array{key: type} 形式。

PHP

编写健壮的PHP代码，规避类型转换陷阱、数组怪癖及常见安全漏洞。

下载

`@return` 必须覆盖所有分支路径的返回值

一个有 if/else 或提前 return 的函数，如果 @return 只写一种类型，就会导致工具误判。比如：

/**
 * 查找用户，不存在时返回 null
 * @param int $id
 * @return User  ← 错！漏了 null
 */
function findUser(int $id): ?User { ... }

正确写法是：

/**
 * @param int $id
 * @return User|null
 */

常见疏忽点：

函数返回 void 却没写 @return void → PHPStan 默认认为有返回值
用了 throw new Exception() 但没加 @throws → 调用方无法预判异常流
返回数组但没注明键名和值类型，如 array{status: string, data: array} 比 array 实用得多

类属性和构造函数参数容易漏掉 `@var` 和 `@param`

类中私有属性如果不加 @var，即使有类型声明（PHP 7.4+ 属性类型），PHPStan 在某些上下文里仍无法推断；构造函数参数同理——光靠 public function __construct(private string $name) 不足以让 IDE 显示完整初始化提示。

实操建议：

每个 private 或 protected 属性都配 @var，哪怕类型已声明
构造函数参数若参与属性赋值，@param 和 @var 最好保持描述一致
避免在 @var 中写“存储用户名”这种模糊描述，换成“用户登录名，长度 3–20 字符”更实用

示例：

/**
 * 用户实体
 */
class User
{
    /** @var string 用户唯一标识，UUID v4 格式 */
    private string $id;
<pre class="brush:php;toolbar:false;"><pre class="brush:php;toolbar:false;">/**
 * @param string $name 用户昵称，允许 Unicode，最大 50 字符
 */
public function __construct(
    private string $name,
) {}

最常被忽略的其实是「一致性」：不是某处写对了就行，而是整个项目里 @param

的顺序、空格、换行、标点（中文句号 or 英文句点）、是否缩进，都会影响团队协作效率和工具解析稳定性。一旦开始用，就得坚持到底——否则过两个月回头看，连自己都分不清哪行注释是认真的，哪行是随手写的占位符。