You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Thanks for reaching out to us. We changed quite some things in the past years, but the documentation is a bit behind on the types. My answer will be the basis to update the documentation.
phpDocumentor supports 3 variants of arrays.
simple arrays, which are the old existing string[] this can be combined to document more complex data types like this string|int[]. Which defines an array of integers and strings. you can go crazy with this, as we do support brackets and combining operators. e.g. (string|(Interface1&Interface2))[] which states that the array value is a string or an object implementing Interface1 and Interface2 . It's up to you how far you will go with this :-).
complex arrays, are the array types where you can specify the index type of the array and the type of all indexes. Right now the index type must be int, string or a combination of both string|int defining the index type is mixed. Like with the simple array's you can go crazy with the value type definition.
array shapes, this one is fairly new. People have been looking for years to define the content of an array, until the static analysers in php (phpstan, psalm) defined a format which is now also supported by phpDoc. An array shape is written like this:
array {
'myKey' : string,
'otherKey': int
}
Again you can go crazy with the type definition of each index. Which can be like any other type. The example above defines that the array has 2 indexes myKey and otherKey with their type definition.
During the rendering of the array in the docs we lose some information, because the simple and complex variant are normalized to an single array type. Which results in the rendering of the complex variant, as that fits best in all cases. e.g string[] will be rendered as array<int|string, string> right now we do not have the information of the original format, so we can not restore this easily.
I hope this answers your question?
The stackoverflow post you linked is mosty correct except for the array shape part.
Seems to have been described once at https://www.phpdoc.org/docs/latest/references/phpdoc/types.html#arrays, according to https://stackoverflow.com/questions/17042613/how-to-document-an-array-of-type:
to define an array type (string) do
$return array string[]
That does nothing: the doc still says
method_name() : array<string|int, string>
In here it is stated to say
@return array [type]
Yet as well that makes no difference.
All difference it makes is that the following changes:
But that is not what I want to modify, I want to modify the actual method entry, which keeps saying
method_name() : array<string|int, mixed>
Is that because it reads the return type off the return type declaration instead of the docblock return flag?
The text was updated successfully, but these errors were encountered: