40

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?

Improve this question

5 Answers 5

Reset to default
32

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;
Improve this answer
Sign up to request clarification or add additional context in comments.

8 Comments

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).
@Sepster 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.
Updated link for ABNF mentioned in Sepster's comment: phpdoc.org/docs/latest/references/phpdoc/types.html
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.
The latest ABNF for types: github.com/php-fig/fig-standards/blob/master/proposed/…
|
19

What works in Phpstorm is:

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

2 Comments

This works perfectly for me. But where did you find this info?
@ColinM blog.jetbrains.com/phpstorm/2022/02/phpstorm-2022-1-eap-3
11

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'.
 * }
 */
Improve this answer

3 Comments

This notation for documenting array structures has never made it into official PHPDoc spec despite serious discussion in 2013-14 about adding it.
Seems to be some related discussion at github.com/phpDocumentor/phpDocumentor2/issues/650
The WordPress guide seems similar to what Psalm recommends: psalm.dev/docs/annotating_code/type_syntax/array_types/…
7

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

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

3 Comments

Tried this in Webstorm 2020.1 EAP for a param description and it mangled the help popup. In my experience this doesn't work.
I can confirm this does not work with VSCode or PHPDocumentor either.
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
0

Modern PHPDoc can be used like following:

  • int[]: an array with only INT values – [1, 4, 6, 8, 9, …]
  • array<int, int>: an array with only INT values – [4 => 1, 8 => 4, 12 => 6, …]
  • string[]: an array with only STRING values – [„foo“, „bar“, …]
  • array<int, string>: an array with only STRING values – [4 => „foo“, 8 => „bar“, …]
  • Order[]: an array with only „Order“-Object values – [Order, Order, …]
  • array<int|string, Order>: an array with INT or STRING as key and „Order“-Object values – [4 => Order, ‘foo‘ => Order, …]
  • array<int|string, mixed>: an array with INT or STRING as key and mixed as values – [1 => 1, 4 => „foo“, 6 => \stdClass, …]
  • array<int, array<int, string>>: an array with INT as key and and an array (with INT as key and string as value) as values – [1 => [1 => „foo“], 4 => [1 => 4], …]
  • array<int, string[]>: an array with INT as key and and an array (with INT as key and string as value) as values – [1 => [„foo“, „lall“], 4 => [„öäü“, „bar“], …]
  • array{output: string, debug: string}: an array with the key „output“ and „debug“, the values are STRING values – [‚output‘ => ‚foo‘, ‚debug‘ => ‚bar‘]
  • array<int, array{output: string, debug: string}>: an array with the key „output“ and „debug“, the values are STRING values – [1 => [‚output‘ => ‚foo‘, ‚debug‘ => ‚bar‘], 3 => [‚output‘ => ‚foo‘, ‚debug‘ => ‚bar‘], …] Examples (only @psalm-): supported by PHPStan & Psalm*
  • list<array{output: string, debug: string}>: an array with the key „output“ and „debug“, the values are STRING values – [0 => [‚output‘ => ‚foo‘, ‚debug‘ => ‚bar‘], 1 => [‚output‘ => ‚foo‘, ‚debug‘ => ‚bar‘], …]

More in here

Improve this answer

Comments

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.