Clean up framework patching

Author: AJenbo

docs/ARCHITECTURE.md

@@ -551,9 +551,14 @@ resolve_class_fully(class)
 ├── 1. resolve_class_with_inheritance(class)
 │   └── Returns base-resolved ClassInfo
 │
-└── 2. For each provider (in priority order):
-    └── if applies_to(class): merge provide(class) into result
-        └── Skips members that already exist (no overwrites)
+├── 2. For each provider (in priority order):
+│   └── if applies_to(class): merge provide(class) into result
+│       └── Skips members that already exist (no overwrites)
+│
+├── 3. Merge members from implemented interfaces
+│
+└── 4. apply_laravel_patches(class, fqn)
+    └── Post-resolution fixups for Laravel classes (see below)
 ```
 
 Provider priority order (highest first):
@@ -566,6 +571,18 @@ Two providers are currently registered in `default_providers()`:
 - **`LaravelModelProvider`** (`virtual_members/laravel.rs`): synthesizes virtual members for classes extending `Illuminate\Database\Eloquent\Model`. Produces relationship properties (methods returning `HasMany`, `HasOne`, `BelongsTo`, etc. generate a virtual property typed from the relationship's generic parameters), scope methods (both the `scopeActive` naming convention and the `#[Scope]` attribute from Laravel 11+ are supported; either style becomes `active()` as both static and instance), Builder-as-static forwarding (`User::where()->get()` resolves end-to-end), accessors (legacy `getXAttribute()` and modern `Attribute` casts), and cast properties (`$casts` array or `casts()` method entries are mapped to PHP types like `datetime` to `\Carbon\Carbon`, `boolean` to `bool`, custom cast classes to their `get()` return type). Highest priority among virtual member providers. Scope methods are also injected onto `Builder<Model>` instances via a post-generic-substitution hook in `type_hint_to_classes_depth` (see "Scope Methods on Builder Instances" below).
 - **`PHPDocProvider`** (`virtual_members/phpdoc.rs`): parses `@method`, `@property`, `@property-read`, `@property-write`, and `@mixin` tags from the class-level docblock stored in `ClassInfo.class_docblock`. Explicit `@method` / `@property` tags are not parsed eagerly during AST extraction; instead, the raw docblock string is preserved and parsed lazily when `provide` is called. For `@mixin` tags, the provider loads the referenced classes and merges their public members. Within the provider, explicit tags take precedence over mixin members. Recurses into mixin-of-mixin chains up to `MAX_MIXIN_DEPTH`.
 
+### Laravel Class Patches
+
+After virtual members and interface members are merged, `resolve_class_fully_inner` calls `apply_laravel_patches(class, fqn)` from `virtual_members/laravel/patches.rs`. Unlike virtual member providers (which *add* new members), patches *modify* existing members' type information to fix framework-specific type inaccuracies that break chain resolution.
+
+The patch system is centralized in a single module with one entry point. Dispatching is based on the fully-qualified class name and trait usage. Current patches:
+
+1. **`Eloquent\Builder::__call` / `__callStatic` return type.** Laravel's `Builder::__call()` is declared as returning `mixed`, but in practice always returns `$this` (scope dispatch, macro dispatch, Query\Builder forwarding). The patch overrides the return type to `static` so that method chains through unknown calls preserve the Builder type.
+
+2. **`Conditionable::when()` / `unless()` return type.** The trait declares `@return $this|TWhenReturnType` but the unresolved method-level template parameter `TWhenReturnType` prevents `is_self_like_type` from recognizing the return as self-referential, breaking method chain resolution on Builder and Collection. The patch replaces the return type with `$this`. Applied to the `Conditionable` trait itself, to `Eloquent\Builder` (which uses the trait), and to any class whose `used_traits` includes `Conditionable`.
+
+3. **Bare `Builder` return types on scope methods.** Handled separately in `scopes.rs` (`is_bare_builder_type`) because it runs at scope-injection time (post-generic-substitution), not during `resolve_class_fully_inner`. Documented in the patch module as part of the inventory but not dispatched from it.
+
 ### Precedence Rules
 
 - **Class own members** always win.

docs/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`Conditionable::when()` / `unless()` chain resolution.** Chained calls after `when()` or `unless()` on Eloquent Builder, Collection, and any class using the `Conditionable` trait now resolve correctly. Previously the unresolved `TWhenReturnType` template parameter in the return type broke chain continuation, so `Builder::where(...)->when(...)->get()` lost type information after `when()`.
 - **`whereHas` / `whereDoesntHave` closure parameter from relation traversal.** The closure parameter in `whereHas`, `orWhereHas`, `whereDoesntHave`, `orWhereDoesntHave`, `withWhereHas`, and related methods is now typed as `Builder<RelatedModel>` instead of `Builder<CallingModel>`. The relation name string (first argument) is resolved by walking the model's relationship methods. Dot-notation chains like `whereHas('category.articles', fn($q) => ...)` follow each segment to the final related model. Works for static calls (`Brand::whereHas(...)`), builder instance calls (`$query->whereHas(...)`), and body-inferred relationships (no `@return` annotation). Falls back to the calling model's builder when the relation cannot be resolved.
 - **Eloquent `where{PropertyName}()` dynamic methods.** Calls like `User::whereBrandId(42)` and `$query->whereLangCode('en')` now resolve instead of producing `unknown_member` diagnostics. For each known column on an Eloquent model (from `$casts`, `$attributes`, `$fillable`/`$guarded`/`$hidden`/`$appends`, `$dates`, timestamps, and `@property` annotations), a virtual `where{StudlyCase}()` method is synthesized on both the model (as a static method) and the Builder (as an instance method). Each method accepts a `mixed` value parameter and returns `Builder<ConcreteModel>`, so chains like `Bakery::whereFlour('rye')->whereApricot(true)->get()` resolve end-to-end.
 - **Eloquent timestamp properties.** Models extending `Illuminate\Database\Eloquent\Model` now automatically get `created_at` and `updated_at` virtual properties typed as `Carbon\Carbon`. Setting `$timestamps = false` suppresses both. Overriding `CREATED_AT` or `UPDATED_AT` constants changes the column name; setting either to `null` disables that column. Explicit `$casts` entries (e.g. `'created_at' => 'immutable_datetime'`) take priority over the timestamp defaults.

docs/todo.md

@@ -154,6 +154,7 @@ unlikely to move the needle for most users.
 | E2   | Project-level stubs as type resolution source                                                                                                                               | Medium      | Medium         |
 | E3   | IDE-provided and `.phpantom.toml` stub paths                                                                                                                                | Low-Medium  | Low            |
 | E6   | Stub install prompt for non-Composer projects                                                                                                                               | Low         | Low            |
+| E7   | [Stub-based framework patches](todo/external-stubs.md#e7-stub-based-framework-patches)                                                                                     | Medium      | Medium         |
 |      | **[Performance](todo/performance.md)**                                                                                                                                      |             |                |
 | P1.5 | [Layered class resolution (zero-copy inheritance)](todo/performance.md#p15-layered-class-resolution-zero-copy-inheritance)                                                  | High        | Very High      |
 | P13  | [Tiered storage: drop per-file maps for non-open files](todo/performance.md#p13-tiered-storage-drop-per-file-maps-for-non-open-files)                                       | Medium-High | Medium-High    |

docs/todo/external-stubs.md

@@ -591,6 +591,7 @@ embedded stubs, built-in symbols would be invisible.
 | E2  | Project-level stubs as a type resolution source           | Medium | indexing.md (byte-level function/constant scanner) |
 | E3  | IDE-provided and `.phpantom.toml` stub paths              | Low    | E2                                                 |
 | E4  | Ship SPL overlay stubs, let external stubs override       | Low    | E2                                                 |
+| E7  | Stub-based framework patches (replace Rust patch system)  | Medium | E2 or E3                                           |
 
 E1 can be done immediately and independently. It provides
 immediate value (GTD on `array_map`, `PDO`, `Iterator`, etc.) with
@@ -663,3 +664,117 @@ answer (`true` or `false`) is written to `[stubs] install` in
 This is not implemented yet. The config writing infrastructure
 (using `toml_edit` to preserve comments and formatting) is a
 prerequisite.
+
+---
+
+## E7. Stub-based framework patches
+
+**Impact: Medium · Effort: Medium · Dependencies: E2 or E3**
+
+Replace the Rust-coded Laravel class patch system
+(`virtual_members/laravel/patches.rs`) with plain PHP stub files that
+override specific declarations. Instead of patching return types in
+Rust after resolution, ship corrected stubs that the normal stub
+loading pipeline picks up at a higher priority than the framework's
+own declarations.
+
+### Motivation
+
+The current patch system (`apply_laravel_patches`) fixes framework
+type inaccuracies by mutating resolved `ClassInfo` in Rust code.
+This works but has drawbacks:
+
+- **Contributor barrier.** Adding a patch for a new framework (Symfony,
+  WordPress, Drupal) or fixing a Laravel type requires Rust knowledge.
+- **Maintenance burden.** Framework updates may change signatures;
+  keeping Rust code in sync is harder than updating a PHP stub file.
+- **Not user-extensible.** Users cannot add their own patches for
+  project-specific quirks without forking PHPantom.
+
+Stub overrides solve all three. A PHP developer who understands the
+framework can write a corrected stub, submit a PR, and never touch
+Rust. Users can drop override stubs into their `.phpantom.toml`
+`[stubs] paths` to fix types locally.
+
+### What the stubs would look like
+
+For the Conditionable `when()`/`unless()` patch, the override stub
+would be:
+
+```php
+namespace Illuminate\Support\Traits;
+
+trait Conditionable {
+    /** @return $this */
+    public function when(mixed $value = null, ?callable $callback = null, ?callable $default = null): mixed {}
+
+    /** @return $this */
+    public function unless(mixed $value = null, ?callable $callback = null, ?callable $default = null): mixed {}
+}
+```
+
+For the Eloquent Builder `__call` patch:
+
+```php
+namespace Illuminate\Database\Eloquent;
+
+class Builder {
+    /** @return static */
+    public function __call(string $method, array $parameters): mixed {}
+
+    /** @return static */
+    public static function __callStatic(string $method, array $parameters): mixed {}
+}
+```
+
+These are standard PHP stub files. They declare only the members that
+need overriding. The stub loading pipeline merges them at a higher
+priority than the framework's own declarations, so the corrected
+`@return` types win.
+
+### Bundled override stubs
+
+PHPantom would ship a set of override stubs for common frameworks,
+organized by framework:
+
+```
+stubs/overrides/
+├── laravel/
+│   ├── Conditionable.stub.php
+│   ├── EloquentBuilder.stub.php
+│   └── ...
+├── symfony/
+│   └── ...
+└── wordpress/
+    └── ...
+```
+
+These would be embedded at build time (like phpstorm-stubs today) and
+loaded into the stub index at a priority above vendor stubs but below
+user `.phpantom.toml` paths. Framework detection (already done for
+Laravel via `composer.json` inspection) controls which set is loaded.
+
+### User-provided override stubs
+
+Once E3 lands, users can place their own override stubs in a
+`.phpantom.toml` `[stubs] paths` directory. Since user paths have the
+highest priority, they override both bundled overrides and vendor
+stubs. This makes the system fully extensible without code changes.
+
+### Migration path
+
+1. Implement E2 or E3 (external stub loading with priority).
+2. Write override stubs for the patches currently in
+   `patches.rs` (Builder `__call`, Conditionable `when`/`unless`).
+3. Add a bundled-overrides loading phase to the stub pipeline,
+   between vendor stubs and user stubs.
+4. Remove the Rust patch functions from `patches.rs`.
+5. Document how to contribute framework override stubs (just PHP,
+   no Rust needed).
+
+### Scope of the Rust patch system until then
+
+The current `patches.rs` module handles the known cases correctly
+and is well-tested. It stays in place until the stub override
+infrastructure from E2/E3 is ready. New patches can still be added
+in Rust in the interim.

docs/todo/laravel.md

@@ -428,6 +428,3 @@ hard-coding the two known classes.  A simpler approach: add
 `@method` tags to bundled stubs for the most common dynamic `with*`
 methods, or document this as a known limitation.
 
-
-
-

example.php

@@ -1768,6 +1768,12 @@ public function demo(): void
         Bakery::whereOvenCode('X9');                  // from $hidden
         Bakery::whereFlour('rye')->whereApricot(true)->get();
         Bakery::where('open', true)->whereFlour('spelt')->fresh()->first();
+
+        // Conditionable when()/unless() chain continuation
+        // The patch replaces the unresolved TWhenReturnType template param
+        // with $this so that chained calls after when()/unless() resolve.
+        BlogAuthor::where('active', 1)->when(true, fn($q) => $q)->get();
+        BlogAuthor::where('active', 1)->unless(false, fn($q) => $q)->first();
     }
 }
 
@@ -5819,6 +5825,7 @@ public function hasOneThrough(string $related, string $through) {}
     class Builder implements \Illuminate\Contracts\Database\Eloquent\Builder {
         /** @use \Illuminate\Database\Concerns\BuildsQueries<TModel> */
         use \Illuminate\Database\Concerns\BuildsQueries;
+        use \Illuminate\Support\Traits\Conditionable;
 
         /**
          * @param  (\Closure(static): mixed)|string|array  $column
@@ -5963,6 +5970,27 @@ public function getIterator(): \ArrayIterator { return new \ArrayIterator([]); }
     }
 }
 
+namespace Illuminate\Support\Traits {
+
+    /**
+     * @template TWhenReturnType
+     * @template TUnlessReturnType
+     */
+    trait Conditionable {
+        /**
+         * @param  (callable($this): TWhenReturnType)|null  $callback
+         * @return $this|TWhenReturnType
+         */
+        public function when(mixed $value = null, ?callable $callback = null, ?callable $default = null): mixed { return $this; }
+
+        /**
+         * @param  (callable($this): TUnlessReturnType)|null  $callback
+         * @return $this|TUnlessReturnType
+         */
+        public function unless(mixed $value = null, ?callable $callback = null, ?callable $default = null): mixed { return $this; }
+    }
+}
+
 namespace Illuminate\Contracts\Database\Eloquent {
     /**
      * @mixin \Illuminate\Database\Eloquent\Builder

src/completion/call_resolution.rs

@@ -114,14 +114,12 @@ fn is_self_like_type(ty: &PhpType) -> bool {
         PhpType::Generic(n, _) => is_self_keyword(n),
         PhpType::Nullable(inner) => is_self_like_type(inner),
         PhpType::Union(members) => {
-            // `static|null`, `$this|void` — filter out non-class types
-            // that cannot produce a class resolution, then check that
-            // every remaining member is self-like.
-            let significant: Vec<_> = members
+            // `static|null` — every non-null member is self-like.
+            let non_null: Vec<_> = members
                 .iter()
-                .filter(|m| !matches!(m, PhpType::Named(n) if n == "null" || n == "void" || n == "never"))
+                .filter(|m| !matches!(m, PhpType::Named(n) if n == "null"))
                 .collect();
-            !significant.is_empty() && significant.iter().all(|m| is_self_like_type(m))
+            !non_null.is_empty() && non_null.iter().all(|m| is_self_like_type(m))
         }
         _ => false,
     }

src/virtual_members/laravel/mod.rs

@@ -80,6 +80,7 @@ mod builder;
 mod casts;
 mod factory;
 mod helpers;
+pub(crate) mod patches;
 mod relationships;
 mod scopes;
 mod where_property;