Larastan 3.x 版本中模型属性类型转换问题的分析与解决

问题背景

在从 Larastan 2.x 升级到 3.x 版本后，开发者遇到了关于模型属性类型转换的新问题。这些问题主要表现在：

1. 动态属性访问时，Larastan 无法正确识别模型中定义的 casts 转换
2. 关联查询中的 Builder 泛型类型提示出现兼容性问题
3. Collection 操作中的类型推断问题

核心问题分析

模型属性类型转换问题

在 Laravel 模型中，开发者通常使用两种方式定义属性类型转换：

1. 传统的 $casts 属性
2. 更灵活的 casts() 方法

在 Larastan 3.x 中，对于使用 casts() 方法定义的类型转换，需要显式添加 PHPDoc 类型注释才能正确识别：

/**
 * @return array{
 *     execution_status: 'Path\\To\\ExecutionStatus',
 *     ms_teams_recipients: 'array',
 * }
 */
protected function casts(): array
{
    return [
        self::MS_TEAMS_RECIPIENTS => 'array',
        self::EXECUTION_STATUS => ExecutionStatus::class,
    ];
}

这种变化源于 Larastan 3.x 对类型推断的严格化处理，旨在提供更精确的静态分析。

关联查询中的 Builder 泛型问题

在构建关联查询时，Larastan 3.x 对 Builder 的泛型类型检查更加严格。例如：

Customer::whereHas('invoices', function (Builder $invoices) {
    /** @var Builder<SaleDocument> $invoices */
    $invoices->today();
})

需要确保 Builder 的泛型参数与模型匹配，并且建议：

1. 使用 ::query() 开始查询链
2. 为方法添加返回类型注释

/** @return Collection<int, Customer> */
public function getCustomersWhoOrderedToday(): Collection
{
    return Customer::query()
        ->whereHas('invoices', function (Builder $invoices) {
            /** @var Builder<SaleDocument> $invoices */
            $invoices->today();
        })
        ->get();
}

Collection 操作的类型推断

在 Collection 操作中，Larastan 3.x 需要更明确的类型提示：

$orderLines = $order->saleableLines->unique(function (SaleDocumentLine $documentLine) {
    return $documentLine->item->{Item::GENERIC_MAGENTO};
});

需要确保：

1. 所有回调函数都有明确的参数类型
2. 链式操作的每个步骤都有可解析的类型

解决方案总结

1. 对于 casts 方法：

   • 添加详细的 PHPDoc 返回类型注释
   • 或暂时回退到使用 $casts 属性

2. 对于查询构建器：

   • 使用 ::query() 开始查询
   • 为方法添加返回类型注释
   • 为 Builder 回调添加泛型类型提示

3. 对于 Collection 操作：

   • 确保所有回调都有参数类型提示
   • 为复杂操作添加中间变量和类型注释

升级建议

从 Larastan 2.x 升级到 3.x 时，开发者应该：

1. 仔细阅读升级指南中的破坏性变更
2. 逐步修复类型检查问题
3. 考虑使用更明确的类型注释
4. 对于复杂查询，可以考虑使用查询作用域简化类型提示

这些变化虽然增加了初期迁移的工作量，但长期来看将提高代码的静态分析准确性和可维护性。