Larastan中如何为Eloquent模型添加自定义属性注解

在Laravel项目中使用Larastan进行静态分析时，开发者经常需要明确指定Eloquent模型包含的属性。虽然Laravel的迁移文件通常会定义数据库结构，但在某些项目中，数据库结构可能分散在不同位置或采用非标准方式管理。本文将介绍几种在Larastan中为模型属性添加类型提示的有效方法。

使用@property注解

最直接的方式是在模型类上方使用PHPDoc的@property注解。这种方法简单明了，适合大多数场景：

/**
 * @property string $name
 * @property int $age
 */
class User extends Model
{
    // 模型代码
}

利用模型存根文件

对于大型项目，建议创建模型存根文件(.stub)。这种方法可以保持模型类本身的整洁，同时提供完整的类型提示：

1. 在项目根目录创建stubs文件夹
2. 为每个模型创建对应的存根文件，如User.stub
3. 在存根文件中添加完整的类型定义

/**
 * @property string $name
 * @property Carbon $created_at
 * @property Carbon $updated_at
 */
class User extends \Illuminate\Database\Eloquent\Model {}

使用model-property泛型类型

Larastan支持model-property<Model>泛型类型，可以在各种PHPDoc标签中使用：

/**
 * @var model-property<User> $name
 * @param model-property<User> $email
 * @return model-property<User>
 */

这种方法特别适合在服务类或仓库类中引用模型属性时使用。

最佳实践建议

1. 对于简单项目，直接在模型类上使用@property注解最为便捷
2. 大型项目推荐使用存根文件，便于集中管理所有模型属性
3. 在非模型类中引用模型属性时，考虑使用model-property泛型类型
4. 保持类型提示与实际数据库结构同步，特别是在团队协作环境中

通过合理使用这些方法，可以显著提高Larastan静态分析的准确性，帮助开发者更早发现潜在的类型相关问题，提升代码质量和开发效率。