Specifying return value in annotation in PHP

Question

Let's say I expect my function to return either null or the array. Is this ok if I add array possible values?

/**
 * @return null|array{
 *     md5: ?string,
 *     data?: array,
 *     size?: ?string,
 *     bit_rate?: ?string,
 *     remote?: ?string,
 *     url?: ?string,
 *     body?: ?string,
 *     refresh?: bool,
 *     refreshRate?: int,
 *     data?: array{
 *         playlist?: array,
 *         repeat?: array,
 *         width?: int,
 *         height?: int,
 *         compression?: mixed,
 *         depth?: int,
 *         alpha_channel?: int,
 *         orientation?: string,
 *         url?: string,
 *     }
 * }
 */

By the way, very interesting question. Phpdoc is used to document php code, but there are still some issues with documenting arrays. That is very strange. Actually the best way is to use some kind of object to store all this data, because arrays have no guarantee, but object properties now have type safety (from php7.4). And if you are working in PhpStorm there is another good way to implement this logic. Here is the link [link](https://stackoverflow.com/a/51032174/13493933). — Sunfline, Jan 12 '21 at 14:25

score 1 · Accepted Answer · answered Jan 12 '21 at 14:22

There is an issue on github, describing this problem. issue

Some code using that feature:

/**
 * @return null|array{
 *     md5: ?string,
 *     data?: array,
 *     size?: ?string,
 *     bit_rate?: ?string,
 *     remote?: ?string("remote", "local"), // documents possible return values
 *     url?: ?string,
 *     body?: ?string,
 *     refresh?: bool,
 *     refreshRate?: int,
 *     data?: array{
 *         playlist?: array,
 *         repeat?: array,
 *         width?: int,
 *         height?: int,
 *         compression?: mixed,
 *         depth?: int,
 *         alpha_channel?: int,
 *         orientation?: string,
 *         url?: string,
 *     }
 * }
 */
function getInfo(): ?array {
    return [
        'md5' => md5('some info'),
        'url' => 'https://example.com/something',
        'data' => [],
        'remote' => 'remote' // possible values `remote` or `local`
    ];
}

I think the best option is to document array in the function description:

/**
 * Returns information about audio source
 *
 * Returns
 * array['md5']            null|string  md5 hash of something
 * array['size']?          null|string  size of audio (should be numeric)
 * array['bit_rate']?      null|string  bit rate
 * array['remote']?        null|string  is it a remote source possible values: "remote", "local" (should be bool)
 * array['url']?           null|string  remote url
 * array['body']           null|string  stream body
 * array['refresh']?       bool         some option
 * array['refreshRate']    int          refresh rate
 * array['data']?          array        audio data
 *      ['playlist']?      array        some playlist data
 *      ['repeat']?        array        some repeat data
 *      ['width']?         int          width of something
 *      ['height']?        int          height of something
 *      ['compression']?   mixed        some compression data
 *      ['delth']?         int          depth value
 *      ['alpha_channel']? int          alpha channel value
 *      ['orientation']?   string       some orientation data
 *      ['url']?           string       url of something
 *
 * @return null|array see above
 */

Specifying return value in annotation in PHP

1 Answers1