Comment associative array in PHP Documentor

Question

I use several associative arrays in my PHP application and I'm using PHP documentor to comment my sources. I never really did specify comments for the arrays in an array, but now I need to do that and don't know how.

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

How do I comment this array in the correct way for @var and @param comments? I could do this like this, but I don't know if this is correct:

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

But how to do this for the @var part?

Exine

Answer 1

For me this works fine in PhpStorm for nice return value description:

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

Blastula

Tried this in Webstorm 2020.1 EAP for a param description and it mangled the help popup. In my experience this doesn't work. – Pinnatiped

I can confirm this does not work with VSCode or PHPDocumentor either. – Aldis

I voted your answer up, but I never accepted it. For me this was exactly what I was looking for back then. Thank you! I accepted it now. :D – Exine

Answer 2

You can't document each key, but you can tell phpDocumentor what type it is.

You could do something like this:

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

Lenten

Has this been confirmed to work with auto-complete/intellisense in any IDEs, I wonder? According to the phpDoc ABNF for type definitions, there's no allowance for a type to be specified for the array index. And it specifies array as @var string[] (the array component is only supposed to be present for "unspecified" arrays). – Homeric

@Homeric I don't think most IDEs are smart enough to recognize this, unfortunately. Your mileage may vary, but I even find Zend Studio's implementation a bit lacking when it comes to this sort of accute type awareness. – Lenten

Updated link for ABNF mentioned in Sepster's comment: phpdoc.org/docs/latest/references/phpdoc/types.html – Coating

The example is confusing, it's not possible by looking at the @var annotation which type is used for the array key or value. Now I can't figure out if the string type hint inside or after the squared brackets is specifying the type of the key. – Exceptional

The latest ABNF for types: github.com/php-fig/fig-standards/blob/master/proposed/… – Srinagar

I think this answer may be misleading. It says "phpDocumentor". However the link actually leads to "PHPLint". I think it's a different software. There's no reason why PHPLint syntax would also be valid phpDoc syntax. – Hydroxy

While this does not answer the question directly, the provided solution is probably the best one. Better only to refactor the array into DTO. – Immiscible

As @Hydroxy pointed out the answer is misleading. The phpDocumentor documentation does not provide key hinting: docs.phpdoc.org/3.0/guide/references/phpdoc/types.html#arrays – Balalaika

Answer 3

What works in Phpstorm is:

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

Cleliaclellan

This works perfectly for me. But where did you find this info? – Kolyma

Answer 4

I would look at the WordPress Inline Documentation Reference for some hints, though it's not currently comprehensive.

Use @param or @var or @property, whichever is appropriate in your context

According to those guidelines, you might document your associative array like this:

/**
 * @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'.
 * }
 */

Claraclarabella

This notation for documenting array structures has never made it into official PHPDoc spec despite serious discussion in 2013-14 about adding it. – Repertory

Seems to be some related discussion at github.com/phpDocumentor/phpDocumentor2/issues/650 – Byelaw

The WordPress guide seems similar to what Psalm recommends: psalm.dev/docs/annotating_code/type_syntax/array_types/… – Julejulee