Add support for Laravel Eloquent scopes

Author: AJenbo

README.md

@@ -16,12 +16,11 @@ PHPantom focuses on completion and go-to-definition and aims to do them really w
 | Go-to-definition | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Go-to-implementation | 🚧 | ✅ | ❌ | ✅ | ✅ |
 | `@mixin` completion | ✅ | 💰 | ✅ | ✅ | 🚧 |
-| `@phpstan-assert` narrowing | ✅ | ❌ | 🚧 | ❌ | 🚧 |
+| `@phpstan` annotations | ✅ | ❌ | 🚧 | ❌ | 🚧 |
 | Conditional return types | ✅ | ❌ | ✅ | ❌ | 🚧 |
+| Laravel Eloquent | ✅ | ❌ | ❌ | ❌ | ❌ |
 | Array shape inference | ✅ | ❌ | ✅ | ❌ | 🚧 |
 | Object shape completion | ✅ | ❌ | ✅ | ❌ | 🚧 |
-| `@phpstan-type` aliases | ✅ | ❌ | 🚧 | ❌ | ❌ |
-| Laravel relationships | ✅ | ❌ | ❌ | ❌ | ❌ |
 | Generator body types | 🚧 | ❌ | 🚧 | ❌ | ❌ |
 | Hover | ❌ | ✅ | ✅ | ✅ | ✅ |
 | Signature help | ❌ | ✅ | ✅ | ✅ | ✅ |
@@ -44,6 +43,7 @@ PHPantom focuses on completion and go-to-definition and aims to do them really w
 - **Generic collection foreach.** Iterating `Collection<User>`, `Generator<int, Item>`, or a class with `@implements IteratorAggregate<int, User>` resolves the loop variable to the element type. Keys too.
 - **Generics.** `@template` with type substitution through inheritance chains and at call sites.
 - **Conditional return types.** PHPStan-style `@return ($param is class-string<T> ? T : mixed)` resolves to the concrete branch at each call site.
+- **Laravel Eloquent.** Relationship methods produce virtual properties with the correct generic type (`$user->posts` resolves to `Collection<Post>`). Scope methods are synthesized from `scope*` prefixed methods and available as both static and instance calls. No application booting, no database access, no ide-helper dependency required.
 - **Everything else you'd expect.** Named arguments completion, destructuring with named keys, chained method calls in assignments, `@deprecated` detection.
 
 ## Project Awareness

docs/CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Virtual member provider abstraction.** Introduced the `VirtualMemberProvider` trait and `VirtualMembers` struct in a new `virtual_members` module. This provides a priority-ordered pipeline for synthesizing members from `@method`/`@property` tags, `@mixin` classes, and framework-specific patterns (e.g. Laravel relationships, scopes, Builder forwarding). All completion and go-to-definition call sites now use the new `resolve_class_fully` entry point, which applies base inheritance resolution followed by virtual member providers. No providers are registered yet, so behavior is unchanged. This is the foundation for upcoming Laravel support.
 - **Laravel relationship properties.** Classes extending `Illuminate\Database\Eloquent\Model` now get virtual properties synthesized from relationship methods. A method returning `HasMany<Post, $this>` produces a `$posts` property typed as `\Illuminate\Database\Eloquent\Collection<Post>`, and `HasOne<Profile, $this>` produces a `$profile` property typed as `Profile`. Supports `HasOne`, `HasMany`, `BelongsTo`, `BelongsToMany`, `MorphOne`, `MorphMany`, `MorphTo`, `MorphToMany`, and `HasManyThrough`. Generic type parameters are extracted from Larastan-style `@return` annotations. The synthesized properties sit at the highest virtual member priority, beating `@property` tags from ide-helper and `@mixin` members. Works with `$this->`, instance variables, relationship methods defined in traits, indirect Model subclasses (through a BaseModel), fully-qualified return types, and cross-file PSR-4 resolution. Chaining through relationship properties (e.g. `$user->profile->getBio()`) resolves to the related model's members.
+- **Laravel scope methods.** Methods starting with `scope` on Eloquent model classes (e.g. `scopeActive`, `scopeOfType`) now produce virtual methods with the prefix stripped and the first letter lowercased (`active`, `ofType`). The first `$query` parameter is removed since Laravel injects it automatically. Scope methods are available as both static and instance methods, so `User::active()` and `$user->active()` both resolve. If the scope method returns `void` or has no return type, the synthesized method defaults to `\Illuminate\Database\Eloquent\Builder<static>`. Custom return types and extra parameters beyond `$query` are preserved.
 - **Union completion sorting.** When a variable has a union type (e.g. `Dog|Cat` from a match or ternary), members shared by all types in the union (the intersection) now sort above members that only exist on a subset of types. Branch-only members display their originating class name as a label detail suffix, giving an at-a-glance visual hint in the completion popup. No completions are removed. Single-type completions are unaffected.
 - **Context-aware class name filtering.** Class name completions are now filtered by syntactic context. `extends` in a class declaration only offers non-final classes, `extends` in an interface only offers interfaces, `implements` offers interfaces only, `use` inside a class body offers traits only, and `instanceof` excludes traits. Constants and functions are also suppressed in these positions. Multi-line declarations and comma-separated lists are handled. Built-in (stub) classes are filtered correctly even before they are fully parsed, using a lightweight source scanner that detects the declaration keyword from the raw PHP source already in memory. Classmap entries whose source is not yet loaded pass through the filter since their kind is unknown.
 - **First-class callable syntax.** PHP 8.1's `strlen(...)`, `$obj->method(...)`, and `ClassName::method(...)` syntax now resolves correctly. The variable holding the callable is typed as `Closure` (for `$fn->bindTo()` etc.), and invoking it with `$fn()` resolves to the underlying function or method's return type. Works with function references, instance methods, static methods, `$this->method(...)`, `self::method(...)`, chained calls on the result, and cross-file resolution.

docs/todo-laravel.md

@@ -329,14 +329,6 @@ end-to-end.
 
 ## Implementation sequence
 
-### Step 4: LaravelModelProvider — scopes
-
-- Scan methods for `scope*` prefix.
-- Synthesize virtual methods (name transformation, param stripping).
-- Mark as both static and instance.
-- Tests: verify `User::active()` and `User::query()->active()` resolve,
-  verify parameter list excludes `$query`.
-
 ### Step 5: LaravelModelProvider — Builder-as-static
 
 - Load Eloquent Builder, extract public instance methods.

example.php

@@ -813,10 +813,14 @@ public function switchInsideCase(string $driver): void
 }
 
 
-// ── Laravel Eloquent Relationship Properties ────────────────────────────────
+// ── Laravel Eloquent Virtual Members ────────────────────────────────────────
 // Methods returning Eloquent relationship types (HasMany, HasOne, BelongsTo, etc.)
 // automatically produce virtual properties. Accessing $author->posts resolves to a
 // Collection<BlogPost>, while $author->profile resolves directly to AuthorProfile.
+//
+// Methods starting with "scope" (e.g. scopeActive) produce virtual methods with
+// the prefix stripped and first letter lowercased (e.g. active). The $query
+// parameter is removed. Scopes are available as both static and instance methods.
 
 class BlogAuthor extends \Illuminate\Database\Eloquent\Model
 {
@@ -838,13 +842,33 @@ public function tags(): mixed
         return $this->belongsToMany(BlogTag::class);
     }
 
+    public function scopeActive(\Illuminate\Database\Eloquent\Builder $query): void
+    {
+        $query->where('active', true);
+    }
+
+    public function scopeOfGenre(\Illuminate\Database\Eloquent\Builder $query, string $genre): void
+    {
+        $query->where('genre', $genre);
+    }
+
     public function demo(): void
     {
         $author = new BlogAuthor();
+
+        // Relationship virtual properties
         $author->posts;                   // virtual property → Collection<BlogPost>
         $author->profile;                 // virtual property → AuthorProfile
         $author->profile->getBio();       // chains to AuthorProfile methods
         $author->tags;                    // virtual property → Collection<BlogTag>
+
+        // Scope methods — instance access
+        $author->active();                // virtual method from scopeActive
+        $author->ofGenre('fiction');       // virtual method from scopeOfGenre ($query stripped)
+
+        // Scope methods — static access
+        BlogAuthor::active();             // also available as static
+        BlogAuthor::ofGenre('fiction');    // $genre parameter preserved, $query stripped
     }
 }