How to document an array of [type]?

Question

Say I have a function like this:

function theFunction() {
    $arr = array();
    for ($i=0;$i<10;$i++) {
        $arr[] = new theObject($i);
    }
    return $arr;
}

I need to document the return type of the function. I could of course just usearray, but that does not provide all the information that can be provided, and doesn't tell the developer much about the true nature of the function.

How do I document the type "array of [type]" in PHPDoc?

Adherence

have you tried @var ObjectType[]? – Luigiluigino

@Luigiluigino no, but searching for that gave a result! :) phpdoc.org/docs/latest/for-users/types.html#arrays – Adherence

See github.com/phpDocumentor/phpDocumentor2/issues/650 – Testament

For anyone visiting this question, there is a much better duplicate question here with a comprehensive set of (correct) answers PHPDoc type hinting for array of objects? – Cylindroid

Answer 1

From the documentation of phpDocumentor

The value represented by Type can be an array. The type MUST be defined following the format of one of the following options:

1. unspecified, no definition of the contents of the represented array is given. Example: @return array

2. specified containing a single type, the Type definition informs the reader of the type of each array element. Only one Type is then expected as element for a given array.

   Example: @return int[]

   Please note that mixed is also a single type and with this keyword it is possible to indicate that each array element contains any possible type.

3. specified containing multiple types, the Type definition informs the reader of the type of each array element. Each element can be of any of the given types. Example: @return (int|string)[]

   Note
   many IDEs probably do not support this notation yet.

Luigiluigino

For multiple types, PHPStorm also seems okay with int[]|string[] but I'm not sure that it should be recommended over (int|string)[]. – Glaydsglaze

I don't think int[]|string[] means the same than (int|string)[]. The first represents an array of int elements or an array of string elements. The latter represents an array that can have elements of both types mixed. – Overcheck

Answer 2

In PHPDoc you can do the following for type hinting array members:

@var array<\My\Folder\ClassName>

UPDATE

You can also explicitly declare the key for associative arrays as follows:

@var array<string, \My\Folder\ClassName>

And according to the answer posted here you can even explicitly declare the keys in case you would like to do so like this:

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

Note: This is tested and works perfectly well in PHP storm:

Doenitz

How do you document the key of the array as well? Could this work: @var array<string, int> (array mapping strings to ints) or @var array<int, Type> (array mapping ints to Type)? Thank you. – Lapboard

The link you provided me are about JavaScript. Associative arrays in PHP don't have numbered keys, the key is a string... How would you document that? Thank you! – Lapboard

@tonix, so sorry for that, I somehow thought this was about Javascript, but I was apparently no longer awake while answering. I updated my answer... – Doenitz

OK! Thank you! This array<KeyType, ValueType> syntax is pretty similar to Java's generics. – Lapboard

This answer is completely wrong. Proof that people don't even check what they copy and paste from Stack Overflow. – Cylindroid

@Cylindroid I always try to thoroughly test and confirm the working of the code in my answers. I added a screenshot from my PHP-storm that I made today. As you see the Intellij IDE understands the type declaration perfectly well, so not sure why you accuse me of copy pasting without checking... – Doenitz

@Doenitz Sorry, should've been more specific. I am referring to the @var array<string> syntax that remains from your original answer. I believe PhpStorm can interpret it but phpDocumentor doesn't use this type of syntax. The standard way to define an array of strings would be @var string[]. The copy/paste comment was directed at all the people who upvoted the original answer with JavaScript context as well, not yourself. – Cylindroid

Answer 3

Array of array with of 2 element:

1. key "priority" value type int
2. key "service" value type string

/** @return array<array{priority: int, service: string}>  */

Brahmana

Answer 4

In PHP 7.4+ you can use type declarations to enforce the return type of a method.

While this is not meant for documentation, it does a better job of documenting than phpDocs did.

In your case, you can do:

function theFunction(): array {
    return [];
}

Pay

Answer 5

If I'm remembering right you supply the return type and a description, can you not put it in the description?

/**
 * blah
 * @return array array of types
 */

Procreant

That's what I'm doing now, but it would be neater to use the standard way if it existed :) – Adherence