A custom Eloquent builder keeps the model it was built for

Author: AJenbo

docs/CHANGELOG.md

@@ -108,6 +108,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - **A Laravel project that requires Larastan gets PHPStan diagnostics too.** PHPStan auto-detection looked only for a direct `phpstan/phpstan` dependency in `composer.json`, so a project that requires `larastan/larastan` and lets it pull `phpstan/phpstan` in transitively never had `vendor/bin/phpstan` recognised, even though the binary was right there. A Laravel project is now recognised through a direct `larastan/larastan` dependency instead: plain PHPStan does not understand Eloquent magic, facades, or container bindings, so a Laravel project that depends on `phpstan/phpstan` directly but has not installed Larastan is still left alone rather than run through an analyser that would misread its own framework.
+- **A custom Eloquent builder keeps the model it was built for.** `SiteCertificate::query()->whereKey($id)->firstOrFail()` resolved to the base `Model`, or reported `subject type 'TModel' could not be resolved`, whenever the model routed its queries through a custom builder. PHP has no generics, so almost nobody writes `@template`/`@extends` on a builder subclass: `class SiteCertificateBuilder extends Builder {}` is the whole class, and the model was lost at whichever method on the chain returns it. The model the query was started from now travels through the builder to the end of the chain, so the result of `firstOrFail()`, `first()`, `get()`, and the rest completes, hovers, and is checked as the concrete model, whether the builder is declared with generics or without. A builder specialised this way also keeps everything the ordinary resolution gives it, including the query-builder methods it reaches through `@mixin`. Closes #362.
 - **`array_filter()` reports the type the filter leaves behind.** A callback that tests the value it is handed proves something about every entry that survives, but the result kept whatever element type went in, so `array_filter($values, fn ($v) => $v !== null)` still looked like it could hold `null` and returning it from a function declared `int[]` was reported as a type error. The surviving values are now narrowed the way the body of an `if` narrows the variable it guards, whether the test is written as an `is_…()` call, a comparison against `null`, an `instanceof` check, or a callable string such as `'is_int'`. The keys were already narrowed this way in the modes that hand the callback a key, and both halves narrow together under `ARRAY_FILTER_USE_BOTH`. Closes #376.
 - **A deprecation warning belongs to the variable it is written on.** The deprecated-usage check typed its subject from a cache keyed by variable name and class, so two methods of the same class that reuse a parameter name shared one entry and whichever type was bound first won. A Laravel controller with a `Request $request` method above a `PendingRequest $request` method reported `Illuminate\Http\Request::get is deprecated` on the HTTP client call, where `get()` is the ordinary way to make a request, and renaming either parameter made the warning vanish. Every subject is now typed in the scope it is written in, so each method, closure, and `instanceof` branch gets its own answer, and a genuine deprecation is still reported no matter which order the methods appear in.
 - **A generic argument left out takes the default its `@template` declares.** `@template TAsync of bool = false` says that a use of the class without a generic argument means `false`, but the parameter was widened to its upper bound instead, so a conditional return keyed on it always picked the else branch. Laravel's HTTP client is where this shows up: `PendingRequest` declares synchronous mode as its default, so an ordinary `Http::get()` looked like it returned a promise rather than a `Response`, and `json()` along with the rest of the response API appeared to be missing on it. A plain request now resolves to `Response` whether it is made through `PendingRequest`, the client factory, or the `Http` facade, and `async()` still resolves to `PromiseInterface` through all three. Contributed by @shuvroroy (#377).

examples/laravel/app/Demo.php

@@ -14,10 +14,12 @@
 use App\Mail\OrderShipped;
 use App\Http\Requests\StoreBakeryRequest;
 use App\Http\Requests\UpdateBakeryRequest;
+use App\Models\Baker;
 use App\Models\Bakery;
 use App\Models\BlogAuthor;
 use App\Models\BlogPost;
 use App\Models\Customer;
+use App\Models\Loaf;
 use App\Models\PostCollection;
 use App\Models\Review;
 use App\Models\ReviewCollection;
@@ -155,6 +157,14 @@ public function eloquentQuery(): void
         BlogAuthor::where('active', 1)->when(true, fn($q) => $q)->get();
         BlogAuthor::where('active', 1)->unless(false, fn($q) => $q)->first();
 
+        // Custom builders keep the model they were built for, whether or
+        // not the builder class declares generics. LoafBuilder declares
+        // none (see app/Models/LoafBuilder.php), BakerBuilder does.
+        Loaf::query()->stale()->where('crust', 'sourdough')->firstOrFail()->getWeight();
+        Loaf::query()->whereKey(1)->first()->getWeight();     // → Loaf|null
+        Loaf::query()->stale()->get();                        // → Collection<Loaf>
+        Baker::query()->active()->firstOrFail()->getName();   // → Baker
+
         // Paginators carry the model element type through foreach
         foreach (BlogAuthor::where('active', 1)->paginate() as $author) {
             $author->profile->getBio();       // → BlogAuthor

examples/laravel/app/Models/Loaf.php

@@ -2,8 +2,10 @@
 
 namespace App\Models;
 
+use Illuminate\Database\Eloquent\Attributes\UseEloquentBuilder;
 use Illuminate\Database\Eloquent\Model;
 
+#[UseEloquentBuilder(LoafBuilder::class)]
 class Loaf extends Model
 {
     public function getWeight(): int { return 0; }

examples/laravel/assertions.php

@@ -146,6 +146,34 @@ function assertMethodReturnType(string $class, string $method, string $expected)
     $result instanceof \Illuminate\Database\Eloquent\Builder
 );
 
+// #[UseEloquentBuilder] hands the query off to the custom builder, and the
+// builder keeps a reference to the model it was built for — which is why the
+// analyzer can name the concrete model at the end of the chain even though
+// LoafBuilder declares no `@template` of its own.
+$result = \App\Models\Loaf::query();
+check(
+    'Loaf::query() returns LoafBuilder (#[UseEloquentBuilder])',
+    $result instanceof \App\Models\LoafBuilder
+);
+check(
+    'LoafBuilder::stale() keeps the chain on LoafBuilder',
+    $result->stale() instanceof \App\Models\LoafBuilder
+);
+check(
+    'LoafBuilder holds the Loaf model it queries',
+    $result->getModel() instanceof \App\Models\Loaf
+);
+
+$result = \App\Models\Baker::query();
+check(
+    'Baker::query() returns BakerBuilder (#[UseEloquentBuilder])',
+    $result instanceof \App\Models\BakerBuilder
+);
+check(
+    'BakerBuilder holds the Baker model it queries',
+    $result->getModel() instanceof \App\Models\Baker
+);
+
 // Model::fresh() on instance (non-existing model returns null)
 $result = $bakery->fresh();
 check(

src/inheritance/mod.rs

@@ -566,37 +566,67 @@ pub(crate) fn resolve_class_with_inheritance(
     merged
 }
 
-/// Whether `class` declares no `@template` of its own but fixes exactly
-/// one ancestor's generics via `@extends`, with an arg count matching
-/// `new_arg_count` — the shape [`rebind_extends_only_generics`] needs.
-pub(crate) fn is_extends_only_generic_rebindable(class: &ClassInfo, new_arg_count: usize) -> bool {
-    class.template_params.is_empty()
-        && matches!(class.extends_generics.as_slice(), [(_, args)] if args.len() == new_arg_count)
+/// Whether `class` declares no `@template` of its own but still takes
+/// `new_arg_count` type arguments through its parent — the shape
+/// [`rebind_extends_only_generics`] needs.
+pub(crate) fn is_extends_only_generic_rebindable(
+    class: &ClassInfo,
+    new_arg_count: usize,
+    class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
+) -> bool {
+    rebindable_parent(class, new_arg_count, class_loader).is_some()
+}
+
+/// The parent whose `@extends` binding [`rebind_extends_only_generics`]
+/// would override, for a class that declares no `@template` of its own.
+///
+/// Two shapes qualify: the class fixes exactly one ancestor's generics
+/// via `@extends`, or it names no generics at all and simply extends a
+/// generic parent. The latter is how nearly every custom Eloquent
+/// builder is written (`class UserBuilder extends Builder {}`): PHP has
+/// no generics, so the subclass silently stands in for `Builder<TModel>`
+/// and a caller that knows the model (`UserBuilder<User>`) has to be
+/// able to bind it.
+fn rebindable_parent(
+    class: &ClassInfo,
+    new_arg_count: usize,
+    class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
+) -> Option<Atom> {
+    if !class.template_params.is_empty() {
+        return None;
+    }
+    match class.extends_generics.as_slice() {
+        [(parent, args)] if args.len() == new_arg_count => Some(*parent),
+        [] => {
+            let parent_name = class.parent_class.as_deref()?;
+            let parent = class_loader(parent_name)?;
+            (parent.template_params.len() == new_arg_count).then(|| atom(parent_name))
+        }
+        _ => None,
+    }
 }
 
-/// Re-derive `class` with its single `@extends` generic binding replaced
-/// by `new_args`, baking the override into every inherited member the
-/// same way the original binding was baked.
+/// Re-derive `class` with its `@extends` generic binding replaced by
+/// `new_args`, returning the overridden raw class alongside the class
+/// re-merged through the parent chain under that binding.
 ///
 /// A `static<TNewKey, TValue>` return type rebind (Laravel's
 /// `Collection::keyBy()`/`groupBy()`/`mapWithKeys()` and friends) names
 /// the calling class, but a concrete collection subclass that only fixes
 /// its key/value types through `@extends` (`final class Sub extends
 /// Collection {}` with `@extends Collection<int, Item>`) has no
 /// `@template` of its own for [`apply_generic_args`] to substitute
-/// against. Overriding the `@extends` binding and re-running the parent
+/// against. Neither has a custom Eloquent builder, which usually names
+/// no generics at all. Overriding the binding and re-running the parent
 /// chain merge reproduces the same baking the original binding went
 /// through, just with the rebind's args in place of the old ones.
 ///
 /// Returns `None` when `class` is not shaped like [`is_extends_only_generic_rebindable`]
 /// describes.
 ///
-/// Only base inheritance merge runs (traits + parent chain) — no virtual
-/// member providers, interface merging, or Laravel patches, the same
-/// trade-off [`crate::virtual_members::resolve_class_base_cached`] makes.
-/// This covers a rebind through real declared methods; a macro registered
-/// on the base collection class after the rebind will not be visible on
-/// the result (see `docs/todo/laravel.md`).
+/// The caller is responsible for layering virtual members, interface
+/// members, and framework patches back on — that is what the returned
+/// raw class is for.
 ///
 /// `class` may be a raw (unmerged) or already fully-resolved `ClassInfo`
 /// — `extends_generics` passes through inheritance merge unchanged either
@@ -610,18 +640,14 @@ pub(crate) fn rebind_extends_only_generics(
     class: &ClassInfo,
     class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
     new_args: &[PhpType],
-) -> Option<ClassInfo> {
-    let [(parent_name, parent_args)] = class.extends_generics.as_slice() else {
-        return None;
-    };
-    if parent_args.len() != new_args.len() {
-        return None;
-    }
+) -> Option<(ClassInfo, ClassInfo)> {
+    let parent_name = rebindable_parent(class, new_args.len(), class_loader)?;
     let fqn = class.fqn();
     let raw = class_loader(fqn.as_str()).filter(|raw| raw.fqn().eq_ignore_ascii_case(fqn.as_str()));
     let mut overridden = raw.as_deref().unwrap_or(class).clone();
-    overridden.extends_generics = vec![(*parent_name, new_args.to_vec())];
-    Some(resolve_class_with_inheritance(&overridden, class_loader))
+    overridden.extends_generics = vec![(parent_name, new_args.to_vec())];
+    let merged = resolve_class_with_inheritance(&overridden, class_loader);
+    Some((overridden, merged))
 }
 
 /// Look up a method's return type through the inheritance chain.

src/type_engine/types/resolution.rs

@@ -418,14 +418,16 @@ fn resolve_named_type(
 
             // Apply generic substitution if the type hint carried generic
             // arguments and the class has template parameters of its own
-            // to substitute, or (a `static<TNewKey, TValue>` rebind on a
-            // concrete collection subclass) fixes a single ancestor's
-            // generics via `@extends` instead.
+            // to substitute, or inherits them from a generic parent it
+            // never bound (a `static<TNewKey, TValue>` rebind on a
+            // concrete collection subclass, a custom Eloquent builder
+            // specialised to its model).
             if !generic_args.is_empty()
                 && (!cls.template_params.is_empty()
                     || crate::inheritance::is_extends_only_generic_rebindable(
                         &cls,
                         generic_args.len(),
+                        class_loader,
                     ))
             {
                 let generic_arg_strings: Vec<String> =

src/virtual_members/resolve.rs

@@ -377,9 +377,35 @@ pub fn resolve_class_fully_with_generics(
 
     let mut result = if !base.template_params.is_empty() {
         Arc::new(crate::inheritance::apply_generic_args(&base, generic_args))
-    } else if let Some(rebound) =
+    } else if let Some((overridden, mut rebound)) =
         crate::inheritance::rebind_extends_only_generics(class, class_loader, generic_args)
     {
+        // The rebind restarts from base inheritance, so everything the
+        // full resolution layers on top (virtual members, `@mixin`
+        // expansion, interface members, framework patches) has to run
+        // again over the re-merged class.  `mark_in_flight` keeps a
+        // provider that resolves this same specialisation from
+        // recursing back into the rebind; on re-entry the caller gets
+        // the base-inheritance-only result instead.
+        let temp_cache;
+        let stage_cache: &ResolvedClassCache = match cache {
+            Some(c) => c,
+            None => match super::cache::active_resolved_class_cache() {
+                Some(active) => active,
+                None => {
+                    temp_cache = super::cache::new_resolved_class_cache();
+                    &temp_cache
+                }
+            },
+        };
+        if stage_cache.write().mark_in_flight(fqn) {
+            let _in_flight = InFlightGuard {
+                cache: stage_cache,
+                fqn,
+            };
+            apply_post_merge_stages(&mut rebound, &overridden, class_loader, stage_cache);
+        }
+        rebound.rebuild_method_index();
         Arc::new(rebound)
     } else {
         base
@@ -543,6 +569,34 @@ fn resolve_class_fully_inner(
 
     // ── Uncached resolution ─────────────────────────────────────────
     let mut merged = resolve_class_with_inheritance(effective_class, class_loader);
+    apply_post_merge_stages(&mut merged, effective_class, class_loader, cache);
+
+    // ── Cache store ─────────────────────────────────────────────────
+    merged.rebuild_method_index();
+    let result = Arc::new(merged);
+    cache.write().insert(cache_key, Arc::clone(&result));
+
+    result
+}
+
+/// Layer virtual members, interface members, and framework patches onto
+/// an inheritance-merged class.
+///
+/// Split out of [`resolve_class_fully_inner`] so that a class re-merged
+/// under an overridden `@extends` binding (see
+/// [`rebind_extends_only_generics`](crate::inheritance::rebind_extends_only_generics))
+/// goes through exactly the same stages instead of stopping at base
+/// inheritance.  `effective_class` is the un-merged class the stages
+/// read structural information from (interfaces, `@implements`
+/// generics, the parent chain); `merged` is the result of running the
+/// inheritance merge over it.
+fn apply_post_merge_stages(
+    merged: &mut ClassInfo,
+    effective_class: &ClassInfo,
+    class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
+    cache: &ResolvedClassCache,
+) {
+    let fqn = effective_class.fqn();
 
     // Whether Laravel-specific resolution should run.  A throwaway
     // cache defaults to `true`, so behaviour is unchanged for
@@ -582,7 +636,7 @@ fn resolve_class_fully_inner(
 
     let providers = default_providers(is_laravel);
     if !providers.is_empty() {
-        apply_virtual_members(&mut merged, class_loader, &providers, Some(cache));
+        apply_virtual_members(merged, class_loader, &providers, Some(cache));
     }
 
     // ── Interface member merging ────────────────────────────────────
@@ -758,11 +812,7 @@ fn resolve_class_fully_inner(
             // right input for the substituted case too.
             let resolved_iface = resolve_class_fully_inner(&iface, class_loader, Some(cache));
 
-            merge_interface_members_into(
-                &mut merged,
-                ClassInfo::clone(&resolved_iface),
-                &iface_subs,
-            );
+            merge_interface_members_into(merged, ClassInfo::clone(&resolved_iface), &iface_subs);
         }
     }
 
@@ -790,15 +840,8 @@ fn resolve_class_fully_inner(
     // `laravel/patches.rs` for the full patch inventory.  Skipped for
     // non-Laravel projects.
     if is_laravel {
-        apply_laravel_patches(&mut merged, &fqn);
+        apply_laravel_patches(merged, &fqn);
     }
-
-    // ── Cache store ─────────────────────────────────────────────────
-    merged.rebuild_method_index();
-    let result = Arc::new(merged);
-    cache.write().insert(cache_key, Arc::clone(&result));
-
-    result
 }
 
 /// Merge resolved interface members into a class, applying `@implements`