Describe an array containing an object (stdClass) with @phpstan-return in PHP DocBlock? - PHPStan

I have an example function in PHP (8.2) that returns an array. Inside this array there is also an object, more precisely stdClass.

I use PHPStan as a static analyzer tool. How can I specify this (object shapes) structure syntactically correct to use it in @phpstan-return using PHPStan Array shapes ?

The example function getBooks():

function getBook(): array
{
    $author = new stdClass();
    $author->firstName = 'John';
    $author->lastName = 'Doe';

    return [
        'id' => 12345,
        'title' => 'Whoever may help me deserves a big "Thank You!"',
        'authors' => $author,
    ];
}

What I already tried and is an invalid syntax:

/**
 * @phpstan-return array{
 *     id: int,
 *     title: string,
 *     authors: object{
 *         firstName: string,
 *         lastName: string,
 *     },
 * }
 */

What I definitely already know is, that the object { .. } part is the syntactically incorrect one here.

As of PHPStan 1.10.12 this is now possible:

https://phpstan.org/writing-php-code/phpdoc-types#object-shapes

So, for your case, that would be written:

/**
 * @return object{
 *     id: int,
 *     title: string,
 *     authors: object{
 *         firstName: string,
 *         lastName: string,
 *     },
 * }
 */

You can define the associative array architecture with the array<keyType, valType|valType|...> pattern:

/** @return array<string, int|stdClass|string> */
function getBook(): array
{ ... }

<kbd><strong>PHPStan demo</strong></kbd>

or specify that it is a mixed array:

/** @return array<mixed> */
function getBook(): array
{ ... }