PHP怎么注释函数_PHP函数注释技巧【要点】-php教程-PHP中文网

PHP函数注释必须遵循PHPDoc标准，以/*开头、/结尾，按@param→@return→@throws→@see顺序书写，类型需与运行时一致，参数名须与函数签名完全相同。

php怎么注释函数_php函数注释技巧【要点】

PHP 函数注释不是可有可无的装饰，而是 IDE 自动补全、PHPStan/PHP_CodeSniffer 检查、以及团队协作的前提。没写对 @param 或漏掉 @return，VS Code 就可能报 Undefined type，PHPStan 也会直接标红。

用 PHPDoc 标准写函数头部注释

PHP 官方不强制注释格式，但所有主流工具（PhpStorm、PHPStan、Psalm、phpDocumentor）都只认 PHPDoc 标准。必须以 /** 开始，每行以 * 对齐，结尾为 */；不能用 // 或 /* */ 替代。

关键标签必须按固定顺序出现：@param → @return → @throws → @see。顺序错乱会导致 PHPStan 解析失败。

@param 类型必须与实际参数类型一致，支持联合类型如 string|int（PHP 8.0+），但旧版工具可能不识别，建议用 mixed + 文字说明
@return 不能省略，即使返回 void 也要显式写 @return void
多个同名标签（如多个 @param）必须一一对应函数参数顺序，错位会导致类型推断完全失效

/**
 * 根据用户 ID 获取格式化昵称，空则返回默认值
 *
 * @param int $userId 用户唯一标识
 * @param string|null $fallback 备用文本，为 null 时返回 '游客'
 * @return string 格式化后的昵称（如「用户#123」）
 * @throws InvalidArgumentException 当 $userId 小于 1 时抛出
 */
function formatUsername(int $userId, ?string $fallback = null): string
{
    if ($userId <h3>@param 类型写法要匹配运行时行为</h3><p>PHP 是动态语言，但 PHPDoc 类型是静态分析的唯一依据。写错类型等于主动关闭类型检查。</p><div class="aritcle_card flexRow artxards">
											<div class="artcardd flexRow">
												<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill5233" title="btpanel phpsite 宝塔面板PHP网站"><img
														src="https://img.php.cn/upload/skill/000/000/081/179040786932301.jpg" alt="btpanel phpsite 宝塔面板PHP网站" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
												<div class="aritcle_card_info flexColumn">
													<a rel="nofollow" href="/xiazai/skill5233" title="btpanel phpsite 宝塔面板PHP网站" class="overflowclass">btpanel phpsite 宝塔面板PHP网站</a>
													<p class="overflowclass">宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理</p>
												</div>
												<a rel="nofollow" href="/xiazai/skill5233" title="btpanel phpsite 宝塔面板PHP网站" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
												</a>
											</div>
										</div>

数组类型统一用 array 或更精确的 string[]（PHP 7.4+）、array（PHP 8.1+），避免混用 array|string 这种模糊写法
对象类型必须写完整类名，如 User 或 \App\Models\User；相对命名空间不被识别
可为空必须显式标注：用 ?string（PHP 7.1+）或 string|null，二者等价，但前者更推荐
回调类型写 callable，不要写 function 或 Closure —— 后者只是 callable 的一种实现

IDE 和静态分析工具依赖注释结构

PhpStorm 的参数提示、自动补全、重构重命名，全部依赖 PHPDoc 中的 @param 名称是否与函数签名一致。如果注释里写 @param int $uid，但函数定义是 function foo(int $userId)，IDE 就无法关联提示。

参数名必须完全一致，包括大小写和下划线风格（$user_id ≠ $userId）
PHPStan 默认只扫描 /** 开头的块注释，/* 或 // 注释中的 PHPDoc 不解析
使用 @deprecated 时，必须跟上替代方案，例如 @deprecated use formatUsername() instead，否则 PHPStan 不会警告调用方
如果函数有默认参数，@param 仍需完整列出，不能省略带默认值的参数