在PHP Documentor中注释关联数组

Question

我在我的PHP应用程序中使用了几个关联数组，并且我正在使用PHP documentor来注释我的源代码。 我从来没有为数组中的数组指定注释，但现在我需要这样做，不知道该怎么办。

$array = array('id' => 'test', 'class' => 'tester', 'options' => array('option1' => 1, 'option2' => 2))

如何以正确的方式在 @var 和 @param 注释中注释这个数组？ 我可以像这样做，但不确定是否正确：

@param string $array['id']
@param string $array['class']
@param int $array['options']['option1']

但如何对@var部分执行此操作？

- Abenil

Answer 1

您无法为每个键编写文档，但可以告诉phpDocumentor它的类型。

您可以进行如下操作：

/**
 * Form the array like this:
 * <code>
 * $array = array(
 *   'id'      => 'foo',          // the id
 *   'class'   => 'myClass',     // the class
 * );
 * 
 * </code>
 *
 * @var array[string]string 
 */
$array;

- Stephen Fuhry

---

我想知道这个在任何IDE中是否已经确认可以与自动完成/智能感知一起使用？根据类型定义的phpDoc ABNF，没有允许为数组索引指定类型。它将数组指定为@var string[]（"未指定"数组应该只出现“数组”组件）。 - Sepster

Sepster在评论中提到的ABNF更新链接：https://www.phpdoc.org/docs/latest/references/phpdoc/types.html - faintsignal

这个例子很令人困惑，通过查看@var注释无法确定数组键或值使用了哪种类型。现在我无法确定方括号内或后面的string类型提示是指定键的类型还是值的类型。 - luukvhoudt

我认为这个答案可能会误导人。它说“phpDocumentor”。然而，链接实际上指向了“PHPLint”。我认为这是一个不同的软件。 PHPLint语法也没有理由是有效的phpDoc语法。 - Gherman

虽然这并没有直接回答问题，但提供的解决方案可能是最好的。最好将数组重构为DTO。 - AnrDaemon

Answer 2

我会查看WordPress内联文档参考获取一些提示，尽管它目前并不全面。

在您的上下文中使用@param或@var或@property，其中适用的内容

根据这些指南，您可以像这样记录关联数组：

/**
 * @property array $my_array {
 *     An array of parameters that customize the way the parser works.
 *
 *     @type boolean $ignore_whitespace Whether to gobble up whitespace. Default true.
 *     @type string $error_level What the error reporting level is. Default 'none'.
 *                               Accepts 'none', 'low', 'high'.
 * }
 */

- Tom Auger

---

尽管在2013-14年进行了严肃的讨论，但记录数组结构的这种符号标记从未被纳入官方的PHPDoc规范中。 - Andrew Sauder

似乎在 https://github.com/phpDocumentor/phpDocumentor2/issues/650 有一些相关的讨论。 - Ben Creasy

WordPress指南似乎与Psalm的建议相似：https://psalm.dev/docs/annotating_code/type_syntax/array_types/#object-like-arrays - Gogowitsch

Answer 3

Phpstorm中有效的功能包括：

/**
 * @return array{ hand: Hand, card: CardType | null }
 */

- Alex

---

这对我来说完美无缺。但是你在哪里找到这个信息的？ - ColinM

Answer 4

在 PhpStorm 中，对于返回值的描述，这对我来说很有效：

/**
 * @param string $requestUri
 * @return array[
 *  'controller' => string,
 *  'action' => string
 * ]
 */

- Richárd Vastag

---

尝试在Webstorm 2020.1 EAP中使用参数描述，但弹出的帮助窗口错乱了。据我的经验，这种方法行不通。 - Chad

我可以确认这在VSCode或PHPDocumentor中也不起作用。 - BlackPanther

我给你的回答点了赞，但是我从来没有接受过它。对我来说，那时候这正是我所寻找的。谢谢！现在我已经接受了。 :D - Abenil