如何通过DocBlock类型提示修复Intelephense代码补全问题？

环境信息 #

• VSCode 1.81.1
• Intelephense 1.9.5（付费版）
• PHP 8.2
• Square SDK 版本：square/square: 30.0.0.20230816

示例代码 #

<?php
declare(strict_types=1);

use Square\SquareClient;
use Square\Models\CatalogObject;
use Square\Models\CatalogItem;

require 'vendor/autoload.php';

$client = new SquareClient([
    'accessToken' => $_ENV['SQUARE_ACCESS_TOKEN'],
    'environment' => 'sandbox'
]);

$res = $client->getCatalogApi()->listCatalog();

/* @var CatalogObject[] $catalog */
$catalog = $res->getResult()->getObjects();

if ($catalog) {

    /* @var CatalogObject $item */
    foreach ($catalog as $item) {

        /* @var CatalogItem $data */
        $data = $item->getItemData();

    }
}

问题及解决方案 #

问题一：补全列表混入全局符号 #

输入$client->getCatalogApi()时，补全列表中出现$client->$_COOKIE这类无效全局符号，需移除。

解决方案：

• 禁用全局变量补全：打开VSCode设置，搜索intelephense.completion.showGlobalVariables，将值设为false。
• 配置工作区根目录：在.vscode/settings.json中添加：

  "intelephense.environment.documentRoot": "${workspaceFolder}"
  

  让Intelephense仅索引当前项目内的符号，减少全局干扰。
• 排除无关资源：通过intelephense.exclude设置，将项目外的无关目录或符号规则加入排除列表，避免无效补全混入。

问题二：类型提示未生效 #

使用/* @var <Type> $variable */添加类型提示后，Intelephense未识别，输入$data->getItem时无法提示getItemData()等方法。

解决方案：

• 修正PHPDoc注释格式：将单星注释/* @var ... */改为双星PHPDoc注释/** @var CatalogItem $data */，Intelephense对标准PHPDoc的解析更可靠。
• 重新构建工作区索引：打开命令面板（Ctrl+Shift+P），依次执行Intelephense: Restart Server和Intelephense: Rebuild Workspace，确保Square SDK的类被完全索引。
• 验证SDK类型定义：检查vendor/square/square目录下的类文件是否包含完整的PHPDoc注释或原生类型声明，部分动态生成的SDK类可能需要Intelephense额外配置才能识别。
• 调整注释位置：将类型注释紧贴变量赋值语句，例如：

  /** @var CatalogItem $data */
  $data = $item->getItemData();
  

  或直接在同一行声明：

  $data = $item->getItemData(); /** @var CatalogItem $data */
  

  提升Intelephense的识别准确性。

内容的提问来源于stack exchange，提问作者JSP