phpDocumentor中如何优雅地标注元组类型返回值

在PHP开发中，我们经常会遇到需要返回元组(tuple)的场景，比如返回一个包含多个值的数组。传统上，开发者可能会使用@return array这样简单的标注，但这无法精确描述数组中每个元素的类型和位置。本文将深入探讨如何在phpDocumentor中规范地标注元组类型的返回值。

数组形状(Array Shapes)标注法

现代PHP生态中，数组形状(Array Shapes)已经成为标注元组类型的事实标准。这种语法最初由Psalm静态分析工具引入，现已被phpDocumentor等主流文档工具广泛支持。

数组形状标注的基本语法是在@return标签中使用花括号{}来定义数组结构：

/**
 * @return array{int, string} 返回包含整数和字符串的元组
 */
function getUserData(): array {
    return [42, 'John Doe'];
}

带键名的结构化标注

对于关联数组形式的元组，我们可以进一步指定键名和对应的类型：

/**
 * @return array{id: int, name: string} 返回包含ID和名称的关联数组
 */
function getUserData(): array {
    return ['id' => 42, 'name' => 'John Doe'];
}

混合类型支持

数组形状标注还支持更复杂的类型组合：

/**
 * @return array{
 *     id: int,
 *     name: string,
 *     roles: string[],
 *     meta?: array<string, mixed>
 * }
 */
function getUserWithMeta(): array {
    // 实现代码
}

工具兼容性说明

虽然数组形状标注已成为社区标准，但不同工具的兼容性可能有所差异：

1. 静态分析工具(如Psalm、PHPStan)完全支持
2. 文档生成工具(如phpDocumentor)支持基本语法
3. IDE支持程度不一，较新版本的PHPStorm等工具支持良好

最佳实践建议

1. 优先使用数组形状标注替代简单的@return array
2. 对于固定位置的元组，使用索引形式标注
3. 对于关联数组，明确标注键名和类型
4. 可选参数使用?标记
5. 保持标注与实际返回值严格一致

通过采用这些标注实践，可以显著提升代码的可读性和静态分析工具的效果，为团队协作和长期维护打下良好基础。