PHP Psalm数组形状注解如何使用合法的多行拆分语法？

多行数组形状注解的支持情况 #

Psalm、PHPStan等主流PHP静态分析工具，以及2023.1及以上版本的PhpStorm，均原生支持你写的多行拆分array{}注解语法，你遇到的解析失败问题通常由版本不匹配或格式细节错误导致。

正确写法规范 #

你示例里的语法本身是合法的，只需要注意以下细节即可正常解析：

• 每个键值对末尾的逗号不能遗漏，最后一个键值对后也支持加尾随逗号
• 嵌套的大括号要保证层级匹配，无遗漏闭合
• 每行PHPDoc开头的*符合标准格式要求，不要省略

合法示例：

/**
 * @return array{
 *     key1: type1,
 *     key2: type2,
 *     key3: array{
 *         nestedKey1: array<string, string>
 *     }
 * }
 */

旧版本兼容方案 #

如果使用的是2023.1之前版本的PhpStorm，或者低版本静态分析工具，无法升级的情况下可以用@psalm-type定义类型别名来拆分复杂结构，同样能降低单行注解长度、提升可读性：

<?php

/**
 * 定义嵌套结构的类型别名
 * @psalm-type NestedType = array{
 *     nestedKey1: array<string, string>
 * }
 */

/**
 * 引用别名实现精简注解
 * @return array{
 *     key1: type1,
 *     key2: type2,
 *     key3: NestedType
 * }
 */
function getResult(): array
{
    // 实现逻辑
}

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