如何在PHPStan的@phpstan-return中正确标注含stdClass的数组结构？

我有一个PHP 8.2的示例函数getBook()，它返回一个array，该数组中包含一个stdClass类型的对象。我使用PHPStan作为静态分析工具，希望通过PHPStan数组形状语法在@phpstan-return中正确标注该返回结构。

示例函数getBook() #

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,
    ];
}

我尝试了以下语法，但它是无效的：

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

我确定其中的object{..}部分是语法错误所在，请问正确的写法是什么？

在PHPStan中，标注stdClass的结构不能直接用object{...}语法，需要明确关联stdClass类型并结合结构约束，有两种常用写法：

方式1：兼容旧版本PHPStan的写法 #

/**
 * @phpstan-return array{
 *     id: int,
 *     title: string,
 *     authors: stdClass&object{
 *         firstName: string,
 *         lastName: string,
 *     },
 * }
 */
function getBook(): array
{
    // 函数实现不变
}

方式2：PHPStan 1.8+的简化写法 #

/**
 * @phpstan-return array{
 *     id: int,
 *     title: string,
 *     authors: stdClass{
 *         firstName: string,
 *         lastName: string,
 *     },
 * }
 */
function getBook(): array
{
    // 函数实现不变
}

原写法无效的原因 #

PHPStan中单独的object{...}代表匿名对象类型，而非stdClass实例。你的函数返回的是明确的stdClass对象，必须明确指定stdClass类型并附加结构约束，PHPStan才能正确识别并完成静态分析。

内容的提问来源于stack exchange，提问作者WebDevPassion