PHP

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

PHP
5480
6
2024-04-02

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

/**
 * 某某方法
 * @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{...}[] 这样的注释,无法提供补全。但是你可以这样写:

结语

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

昵称
邮箱
网址
Kenvix的头像 2024-06-03 20:50

果然PHP数组这逆天东西,想声明类型的结果就会变得更逆天...

jiyouzhan的头像 2024-05-17 18:33

这篇文章写得深入浅出,让我这个小白也看懂了!

inori的头像 2024-05-07 21:42
inori

最后一个例子看起来有点像TypeScript里面就地声明的数据结构

九凌网络的头像 2024-04-08 15:17

表示看不懂

overtrue的头像 2024-04-02 17:01
overtrue

基哥 666

mokeyjay的头像 2024-04-02 17:11
mokeyjay 博主

超,你上班又摸鱼了🤪