当这些数组是映射（又名哈希表）时，如何在 PHPDoc 中记录数组的类型？

Question

PHPDoc 是 JavaDoc 对 PHP 的改编。通过注释中的正确语法，您可以使用它来记录事物的类型。然后，IDE 等工具可以使用该元数据。

这是一个使用“简单”字符串数组的示例。

/**
  * @param string[] $strings  This parameter is blah blah blah.
  */
public function foo($strings) {
    // ...
}

但是 PHP“数组”也可以用作映射（又名哈希表，又名字典）。以下是 PHP 文档 ( http://php.net/manual/en/language.types.array.php ) 中的示例：

$array = array(
    "foo" => "bar",
    "bar" => "foo",
);

现在假设我们修改我们的函数foo以接受$array上面的内容：字符串数组 => 字符串。

/**
  * @param ??????? entries  This parameter is blah blah blah.
  */
public function foo($entries) {
    // ...
}

$entriesPHPDoc 中应该如何表示的类型？

http://www.phpdoc.org/docs/latest/guides/types.html#arrays甚至没有提到该语言中存在的这种构造。

Answer 1

您至少可以记录$entries应该是 s 数组string：

/**
 * @param string[] entries
 */
public function foo($entries) 
{
    // ...
}

但是，您还可以修改方法签名以添加类型声明array：

/**
 * @param string[] entries
 */
public function foo(array $entries) 
{
    // ...
}

此外，您可以通过编写自己的断言或使用以下方法来防止传入无效值beberlei/assert：

use Assert\Assertion;

/**
 * @param string[] entries
 * 
 * @throws InvalidArgumentException
 */
public function foo(array $entries) 
{
    Assertion::allString($entries);
    Assertion::allString(array_keys($entries));

    // ...
}

这对文档块没有多大帮助，但它记录了代码本身中与参数相关的要求。