PHP项目用AI生成文档注释前，须先配置phpDocumentor等静态分析工具并验证骨架解析正常；AI仅补全内容，不可替代规范，需严格按现有签名、类型（含联合类型）、use语句和异常实际抛出位置生成注释，避免破坏契约或引发解析错误。
PHP项目里用AI生成文档注释，先看phpDocumentor是否已就位
AI不能直接替代文档结构规范，它只是补全内容的工具。如果你的项目没配phpDocumentor或phpstan这类静态分析基础，AI生成的注释大概率和实际签名对不上——比如函数参数名写成$user_id，AI却输出$id，后续生成API文档时会直接报错。
实操建议：
- 先跑一次
phpdoc -d src -t docs/api，确认能正常解析出类/方法骨架（哪怕注释为空） - 检查
phpcs是否启用Squiz.Commenting.FunctionComment规则，避免AI生成的注释格式被CI拒绝 - 把
@param、@return这些tag当成必填字段来喂AI，别只丢一段自然语言描述过去
用Cursor或Continue插件给PHP函数加注释，得关掉“自动补全变量名”
这类AI编码助手默认会尝试推断变量类型并改写参数名，但在PHP里常有$data、$row这种弱语义命名，AI强行改成$userDataArray反而破坏原有调用契约。
常见错误现象：AI生成的@param array $userDataArray导致IDE跳转失效，因为源码里实际是function handle($data)。
立即学习“PHP免费学习笔记（深入）”；
使用场景下要手动干预：
- 选中函数体后触发AI指令，明确说：“按现有参数名生成phpdoc，不修改签名，类型按
gettype()返回值写” - 如果函数含
array|false这种联合类型，AI容易漏掉|false，必须人工补上 - 遇到
static::或self::调用的静态方法，AI常误判为void，需核对返回值是否真无返回
批量给Laravel控制器加注释，绕不开__invoke和中间件反射
Laravel控制器方法常被中间件包裹，AI看到public function index(Request $request)可能只注释$request，却忽略隐式注入的$user（来自auth中间件绑定）。
性能影响点：AI若把整个Request对象展开成10个@param，会导致phpDocumentor解析变慢，且PHPStorm索引卡顿。
实操建议：
- 对
__invoke方法单独处理，提示AI：“此方法等价于Route绑定的闭包，参数仅含Request和路由参数，不包含中间件注入对象” - 用
php artisan route:list --json导出路由参数名，粘贴进AI上下文，比让它猜靠谱得多 - 避免让AI处理
__call或__get魔术方法——它大概率会生成错误的@return类型
用Claude或Qwen写@throws注释，必须对照try/catch块里的throw new
AI倾向于泛化异常类型，比如看到throw new Exception('not found')就写@throws Exception，但PHP项目通常用NotFoundException或ValidationException子类，这样写会让phpstan报错“未声明具体异常类型”。
容易踩的坑：
- AI读不到
use语句，可能写出@throws \App\Exceptions\InvalidInputException，而实际是use App\Exceptions\InvalidInputException;，导致文档生成失败 - 当
catch块里有Log::error()但没throw，AI仍可能虚构@throws，必须删掉 -
finally里抛出的异常不会被AI识别，这类得人工补
复杂点在于：有些异常只在特定环境抛出（如RedisException仅在Redis连接失败时触发），AI无法感知运行时条件，这类@throws宁可不写，也别写错。
