PHPantom的Laravel深度支持:Eloquent关系、作用域、访问器与Builder链完整解析
PHPantom的Laravel深度支持:Eloquent关系、作用域、访问器与Builder链完整解析
👋 还在为 Laravel 项目里 Eloquent 的"魔法"属性头疼吗?PHPantom 是一个用 Rust 编写的高速 PHP language server,内置深度类型智能:Generics、PHPStan 注解与完整的 Laravel 支持开箱即用。无需 ide-helper、无需访问数据库,它就能理解你的 Eloquent 模型——关系、作用域、访问器、Builder 链,全都解析到位。
为什么 Eloquent 需要"深度理解"?
Laravel 的 Eloquent 模型大量依赖运行时"魔法":
$post->author并不是真实属性,而是author()关系方法推导出来的;User::where('active', 1)里的where来自__callStatic的 Builder 转发;$user->full_name可能来自一个getFullNameAttribute()方法;- 访问器、
casts、作用域(scope)也都藏在命名约定或注解里。
传统补全工具在这里往往"猜",而 PHPantom 通过 src/virtual_members/laravel/ 模块把这些约定静态推断成真实的类型信息。
Eloquent 关系:从方法到属性
核心实现位于 src/virtual_members/laravel/relationships.rs。它做的事可以概括为两步:
- 识别关系方法。
hasOne、hasMany、belongsTo、belongsToMany,以及全部morph*与*Through变体都在内置映射表中,即使命体里没有@return注解,PHPantom 也能从方法体文本推断出关系类型。 - 合成虚拟属性。
HasMany<Post, $this>这样的返回类型会被转换为$this->posts上的Illuminate\Database\Eloquent\Collection<Post>属性类型。
此外,模块还维护了一份关系查询方法清单(has、whereHas、with、whereRelation 等 20 多个方法),从而在 whereHas('comments', fn...) 这类闭包中正确推断回调参数的类型——这正是 Eloquent 里最容易"类型丢失"的地方。
📌 想在本地验证效果?示例项目 examples/laravel/app/Models/Bakery.php 里就有一个典型的 Bakery 模型:baguettes() 返回 HasMany<Loaf, $this>,headBaker() 返回 HasOne<Baker, $this>。
作用域(Scope):约定即接口
作用域解析在 src/virtual_members/laravel/scopes.rs,同时支持两种写法:
| 写法 | 识别方式 | 说明 |
|---|---|---|
scopeActive(...) |
命名约定 | 前缀去掉 scope、首字母小写,得到公开名 active |
#[Scope] 特性方法 |
Laravel 11+ | 保留方法原名,且要求方法非 public |
PHPantom 会为每个作用域合成两个虚拟方法:静态版本(User::active())和实例版本($user->active()),并自动剥离框架注入的第一个 $query 参数。如果作用域没有声明返回类型,则默认推断为 Builder<static>——这意味着链式调用后类型依然精确。
访问器与 Mutator:新旧写法都认
src/virtual_members/laravel/accessors.rs 同时覆盖两代访问器风格:
- 传统写法:
getFullNameAttribute()→ 虚拟属性$full_name;对应的setXxxAttribute()被识别为 Mutator。 - 现代写法(Laravel 9+):返回
Illuminate\Database\Eloquent\Casts\Attribute的方法,如fullName(): Attribute→ 虚拟属性$full_name;带泛型的Attribute<string>还能读出属性的具体类型。
属性名按 Laravel 的命名约定自动做 camelCase → snake_case 转换,$casts 属性(见 casts.rs)也会被解析,让 protected $casts = ['status' => OrderStatus::class] 这类声明带来真实的枚举/数组/datetime 类型。
Builder 链:Model::where(...) 如何获得类型
这是 PHPantom 对 Laravel 支持中最有意思的部分,实现在 src/virtual_members/laravel/builder.rs:
- 静态转发。Laravel 的
Model::__callStatic()会把静态调用转发到static::query()。PHPantom 把 Eloquent Builder 的全部公共实例方法合成为模型上的静态虚拟方法。 - 类型替换。Builder 返回类型中的
static、$this、模板参数(如TModel)会被替换为具体的模型类名,所以$user->where('id', 1)->first()一路链下去,类型始终锚定在User上。 - 自定义 Builder。通过
#<a href="https://link.gitcode.com/i/0994c45c7ecb052a3af4095f7b178aab" target="_blank">UseEloquentBuilder]或HasBuilder声明的自定义 Builder(如 [examples/laravel/app/Models/Loaf.php 中的用法)同样被支持;自定义 Builder 加载失败时会安全回退到标准 Eloquent Builder。
配套的路由、门面、宏等能力分散在 builder_injection.rs、facade.rs、macros.rs 等模块中,共同构成完整的 Laravel 类型体系。
上手:三步开启 Laravel 智能
🚀 PHPantom 对 Laravel 是零配置的——不需要 ide-helper,也不需要连接数据库:
- 安装 PHPantom 并配置到你的编辑器(参考 docs/editor-setup.md);
- 打开你的 Laravel 项目根目录,等待后台索引完成(30K 文件量级约 2 秒就绪);
- 在模型、Controller、Blade 模板中正常输入
$user->、Post::即可看到带类型的补全与诊断。
更细节的配置项见 docs/configuration.md,Laravel 相关路线图见 docs/todo/laravel.md。
总结
| 能力 | 实现位置 | 效果 |
|---|---|---|
| 关系属性推断 | relationships.rs | $post->author 拥有精确类型 |
| 作用域解析 | scopes.rs | 约定式 + #[Scope] 双支持 |
| 访问器/Mutator | accessors.rs | 新旧写法均生成虚拟属性 |
| Builder 链 | builder.rs | 静态调用全程保持具体模型类型 |
PHPantom 把 Laravel 的"魔法"变成了可静态分析的"知识":关系、作用域、访问器、Builder 链不再是 IDE 里的灰区,而是补全、跳转、诊断与重构都能依赖的坚实类型。如果你正在维护一个 Laravel 项目,它就是值得立即试用的选择。✨