如何让PhpStorm自动提示/补全函数返回数组的键名

问题根源 #

PhpStorm 没法自动为test()函数返回的数组提供键名补全，本质是因为PHP是弱类型语言——默认情况下，函数没有明确的返回结构提示，IDE只能知道这个函数返回一个数组，但无法确定数组内部包含哪些具体的键值对。

而直接赋值的数组则不同：IDE能直接解析赋值语句里的数组结构，所以可以实时生成准确的键名补全提示。

解决方法 #

下面是几种可靠的实现方式，按通用性排序：

1. 用PHPDoc注释明确返回数组结构（推荐）

这是兼容所有PHP版本、且PhpStorm最认可的方案。给函数添加@return注释，精准定义返回数组的键和对应值的类型：

/**
 * @return array{'one': int, 'two': int}
 */
function test(){
    return array(
        'one' => 1,
        'two' => 2
    );
}

$test = test();
echo $test['']; // 现在会自动提示 'one' 和 'two'

添加注释后，PhpStorm就能精准识别返回数组的结构，补全功能立刻生效。

2. 临时变量辅助推断（简易方案）

如果不想写注释，可以在函数内部先把数组赋值给一个临时变量，再返回该变量。这种情况下，PhpStorm通常能通过变量的赋值逻辑推断出数组结构：

function test(){
    $result = [
        'one' => 1,
        'two' => 2
    ];
    return $result;
}

不过这种方法的稳定性不如PHPDoc注释，当函数逻辑复杂（比如有条件分支返回不同数组）时，IDE可能会丢失结构推断。

3. 用PHP 8.1+的结构化类替代数组（进阶）

如果你的项目使用PHP 8.1及以上版本，可以考虑用readonly类来模拟结构化数据，替代数组。这种方式不仅能获得完美的IDE补全，还能获得类型安全：

readonly class TestResult {
    public function __construct(
        public int $one,
        public int $two
    ) {}
}

function test(): TestResult {
    return new TestResult(1, 2);
}

$test = test();
echo $test->one; // 自动补全属性名，体验比数组更好

当然这是替代方案，如果你必须使用数组，第一种方法依然是最优选择。

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