VS Code 中 PHP Doc Blocker 扩展无法正确推断PHP函数返回类型注释

核心成因 #

• php-docblocker 本身不内置PHP代码解析引擎，默认遇到未显式声明返回类型的函数时，会直接输出兜底的@return void，不会主动解析函数体内部的实际返回逻辑
• 配置项未开启和已安装的Intelephense的联动，无法借助Intelephense的类型识别能力拿到正确的返回值类型
• 空的functionTemplate配置触发了扩展的默认兜底模板，没有使用动态解析到的类型做填充

操作步骤 #

1. 前置环境校验 #

• 将php-docblocker扩展更新到最新版本，旧版本无对接第三方PHP语言服务的能力
• 验证Intelephense的识别能力：将光标放到simulations()方法内的hasMany(Simulation::class)代码上，查看悬浮提示，如果能直接显示返回值为\Illuminate\Database\Eloquent\Relations\HasMany，说明基础环境正常；如果显示为未知类型，需要先检查项目vendor目录是否被VS Code的文件扫描规则排除，等Intelephense正确识别到Laravel框架的类定义后再做后续配置。

2. 调整核心功能配置 #

在VS Code的settings.json配置文件中添加以下规则：

// 开启对接外部PHP语言服务的类型解析能力
"php-docblocker.useDefaultTypeResolver": true,
// 允许解析函数体内部的返回值逻辑，不局限于函数签名的显式声明
"php-docblocker.resolveReturnTypesFromFunctionBody": true

3. 修正注释模板配置 #

将现有空的functionTemplate配置替换为以下规则，确保返回值部分使用动态解析的类型填充：

"php-docblocker.functionTemplate": {
  "message": {
    "format": "Undocumented function"
  },
  "param": {
    "format": "@param ${type} ${var}"
  },
  "return": {
    "format": "@return ${type}"
  },
  "extra": []
}

完成配置后重启VS Code，让两个扩展的语言服务完成初始化连接，再触发注释生成即可输出预期的返回值类型。

内容的提问来源于stack exchange，提问作者João