Как документировать типы массивов в 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 даже не упоминается о такой конструкции, существующей в языке.
Решение
Вы можете по крайней мере документировать, что $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));
// ...
}
Это не очень помогает с докблоком, но документирует требования к вашим параметрам в самом коде.
Другие решения
Я бы порекомендовал избегать использования массивов для структур данных в коде 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;
detector