如何在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) {
    // ...
}

在PHPDoc中，$entries的类型应该如何表示？

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

- WalterGR

---

我认为$entries的类型应该简单地声明为array。我认为这是phpdoc的一个限制。我猜想意图是为了向其他开发人员记录参数的结构，而不是为了类型提示，因为这对于数组永远不起作用。您可以在描述中编写进一步的文档。如果您想要更清晰的解决方案，那么您应该编写一个表示哈希映射的类class foobar { public $foo; public $bar; }并将其声明为foobar类型。在这种情况下，类型提示也将起作用。 - steven

我认为这个问题仍在 https://github.com/phpDocumentor/fig-standards/issues/7 上继续讨论。 - Ben Creasy

根据phpdoc（https://docs.phpdoc.org/3.0/guide/references/phpdoc/types.html＃arrays）的说明，数组文档相当有限。您可以使数组未指定（即 @return array），具有单个类型（即 @return int []）或多个类型（即 @return（int | string）[]）。但是，没有提到更复杂的数组，例如关联数组。 - Dave F

Answer 1

您至少可以记录$entries应该是一个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));

    // ...
}

这并没有对docblock有很大帮助，但它在代码本身中记录了你参数的需求。

- localheinz

Answer 2

我建议在 PHP 代码中避免使用数组作为数据结构。具有明确定义属性的类更加适合。

作为解决方法，您可以使用存根类来描述数组结构，但是您需要将数组转换为对象才能从中受益。

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

/**
 * @property $foo
 * @property $bar
 */
class MyStub {}

/** @var MyStub $object */
$object = (object)$array;

// IDE completion and inspections are now available
$object->foo .= $object->bar;

// optional casting back to array
$array = (array)$object;

- vearutop