Как документировать типы массивов в PHPDoc, когда эти массивы являются картами (или хеш-таблицами)?

Question

Как документировать типы массивов в PHPDoc, когда эти массивы являются картами (или хеш-таблицами)?

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

Как следует тип $entries быть представленным в PHPDoc?

http://www.phpdoc.org/docs/latest/guides/types.html#arrays даже не упоминается о такой конструкции, существующей в языке.

2

arrays dictionary hashtable php phpdoc

Решение

Другие решения

Я бы порекомендовал избегать использования массивов для структур данных в коде 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;

0

Источник

Accepted Answer

Вы можете по крайней мере документировать, что $entries должен быть массивом strings:

/**
* @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));

// ...
}

Это не очень помогает с докблоком, но документирует требования к вашим параметрам в самом коде.

1