Larastan 3.x 版本中模型属性类型转换的升级指南

问题背景

在 Laravel 项目中，Larastan 作为静态分析工具，能够帮助开发者提前发现潜在的类型错误。近期 Larastan 从 2.x 升级到 3.x 版本后，许多开发者遇到了关于模型属性类型转换的新问题。

核心问题分析

在 Larastan 3.x 中，对于模型属性类型转换的处理变得更加严格。具体表现在：

1. 当使用 casts() 方法定义属性类型转换时，需要显式声明返回类型
2. 动态属性访问的类型推断规则发生了变化
3. 查询构建器的泛型类型检查更加严格

解决方案

1. 模型属性类型转换的修复

在 Laravel 模型中，如果使用 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,
    ];
}

或者可以使用传统的 $casts 属性来避免这个问题：

protected $casts = [
    'ms_teams_recipients' => 'array',
    'execution_status' => ExecutionStatus::class,
];

2. 查询构建器的类型提示

对于 Eloquent 查询构建器，需要更精确的类型提示：

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

3. 集合操作的泛型处理

对于集合操作，需要明确指定集合元素的类型：

/** @var Collection<int, SaleDocumentLine> $orderLines */
$orderLines = $order->saleableLines->unique(function (SaleDocumentLine $documentLine) {
    return $documentLine->item->{Item::GENERIC_MAGENTO};
});

升级建议

1. 逐步检查项目中所有的模型类，确保类型转换定义符合新规范
2. 为所有返回集合的方法添加泛型类型注释
3. 考虑在查询构建器前使用 query() 方法以获得更好的类型推断
4. 对于复杂的集合操作，添加必要的类型提示

总结

Larastan 3.x 版本对类型系统的检查更加严格，这虽然增加了升级的复杂度，但能帮助开发者构建更加健壮的应用程序。通过遵循上述建议，可以顺利过渡到新版本，并享受更强大的静态分析能力带来的好处。