PHPStan报StdClass属性类型错误：修复下拉选项类型不匹配问题

问题场景 #

在Laravel v10.48.8项目中，我用以下代码构建带前置空选项的下拉框选项：

return State::all()
    ->map(fn (State $state) => (object) [
        'value' => $state->id,
        'label' => $state->name,
    ])
    ->sortBy('label')
    ->prepend((object) [
        'value' => null,
        'label' => '',
    ]);

运行Larastan v2.9.5（基于PHPStan v1.10.67）检测时，触发如下类型错误：

Parameter #1 $value of method
Illuminate\Support\Collection<int,object{
value: int, label: string}&stdClass>::prepend()
expects
object{value: int, label: string}&stdClass,
object{value: null, label: string}&stdClass given.
💡 Property ($value) type int does not accept type null.

原因是PHPStan通过map中State->id的类型，推断出集合中对象的value属性为int类型，但前置的空选项value是null，导致类型不兼容。

修复方案 #

方案一：显式声明对象形状（推荐，业务逻辑层解决） #

通过注释明确告诉PHPStan，map返回的对象value属性是可空整数类型，这样prepend的空选项就能匹配类型。

可以直接在匿名函数上添加类型注释：

return State::all()
    ->map(/** @return object{value: ?int, label: string} */ fn (State $state) => (object) [
        'value' => $state->id,
        'label' => $state->name,
    ])
    ->sortBy('label')
    ->prepend((object) [
        'value' => null,
        'label' => '',
    ]);

或者用更清晰的闭包写法：

return State::all()
    ->map(function (State $state): object {
        /** @var object{value: ?int, label: string} $item */
        $item = (object) [
            'value' => $state->id,
            'label' => $state->name,
        ];
        return $item;
    })
    ->sortBy('label')
    ->prepend((object) [
        'value' => null,
        'label' => '',
    ]);

方案二：使用普通函数替代匿名函数 #

正如你发现的，用普通函数代替匿名函数可以规避这个问题——PHPStan对普通函数的类型推断逻辑不同，即使不额外声明类型，也不会严格限制value的类型。不过建议还是给普通函数加上返回类型注释，保持代码的类型安全性：

function mapStateToOption(State $state): object {
    /** @var object{value: ?int, label: string} $item */
    $item = (object) [
        'value' => $state->id,
        'label' => $state->name,
    ];
    return $item;
}

// 业务代码中调用
return State::all()
    ->map('mapStateToOption')
    ->sortBy('label')
    ->prepend((object) [
        'value' => null,
        'label' => '',
    ]);

方案三：显式保留value的可空性 #

在map中强制将value转为可空类型，让PHPStan识别到它可以接受null：

return State::all()
    ->map(fn (State $state) => (object) [
        'value' => $state->id ?? null,
        'label' => $state->name,
    ])
    ->sortBy('label')
    ->prepend((object) [
        'value' => null,
        'label' => '',
    ]);

关于魔术属性$id的类型疑问 #

Larastan默认会根据Laravel Model的数据库迁移、$casts配置，或者主键的默认规则推断魔术属性的类型。因为自增主键通常是non-nullable的int类型，所以Larastan默认将$id推断为int而非?int。如果不想修改Model注释，用上面的业务层方案就能解决问题。

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