如何在 PHP 中用注释声明数组的结构

在开发过程中我们常常会遇到这样的注释：

/**
 * 某某方法
 * @param array $data
 * @return void
 */

// ...

/**
 * @var array $data
 */

这种注释就叫做 PHPDoc，很久以前我也介绍过 —— 《PHP注释的艺术——phpDoc规范》不过早期规范只能用来描述一些基本变量类型
有时候数组中会有一些相对固定的键，或者是更加复杂的结构，但是场景又没有复杂到需要用结构类的程度。这时你可能会希望用注释的方式说明这个数组的结构方便日后审阅，最好还能让 IDE 识别并提供智能补全，该怎么做呢？

一维数组

例如 id（int）列表、标签名称（string）列表等基础变量类型或者类可以直接添加 [] 来表示，例如：

/**
 * @param int[] $ids
 * @param User[] $users
 * @param (int|string)[] $data 整数或字符串数组
 *
 * 不嫌麻烦的话还能这样写
 * @param array<User> $users
 */

一维键值对

可以通过 <> 来指定键和值的类型

/**
 * @param array<string, User> $data
 */

表示这是一个字符串键名对应 User 实例值的数组

多维数组

/**
 * @var array{
 *   id: int,
 *   name: string,
 *   attributes: array{
 *     height: float,
 *     weight: float
 *   }
 * } $product
 */

那如果我想表示 $product 数组呢？
当前版本的 PHPStorm 无法识别 array{...}[] 这样的注释，无法提供补全。但是你可以这样写：

结语

什么？你说比这更复杂的场景怎么写？
那咱们就写个结构类吧，别偷懒，好吗？