correct $this / static for callable

Author: AJenbo

docs/CHANGELOG.md

@@ -54,6 +54,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`@var` without variable name for array access.** `/** @var array<int, Customer> */` followed by `$thing = []; $thing[0]->` now resolves the element type. Previously `find_iterable_raw_type_in_source` only matched annotations that explicitly named the variable (e.g. `/** @var array<int, Customer> $thing */`). The scanner now also matches no-variable-name `@var` annotations when the line immediately following the docblock is an assignment to the target variable. Works with `array<K, V>`, `list<V>`, `array<V>`, and all other generic iterable forms.
 - **Inferred element type from array literals.** `$thing = [new Customer()]; $thing[0]->` now resolves to `Customer`. When an array literal contains positional (non-keyed) entries like `new ClassName()`, the element types are inferred and combined into a `list<Type>` annotation. Previously only string-keyed entries (for array shapes) and push-style assignments (`$var[] = expr`) were tracked; positional entries were silently discarded. Mixed arrays with both keyed and positional entries infer the positional elements as `list<>` when no string keys are present.
 - **Inline array literal with index access.** `[Customer::first()][0]->` now resolves to the element type. Subject extraction recognises inline array literals (bracket pairs without a `$var` prefix) and produces a structured subject. The resolver splits the literal from the index segments, resolves each comma-separated element via call-chain or `new` expression resolution, and returns the element classes. The inline-literal handler runs before the enum-case/static-member check so that subjects containing `::` inside brackets are not misinterpreted.
+- **`$this` in callable parameter types resolves to receiver class.** When a method signature uses `$this` or `static` in a callable parameter type (e.g. `@param callable($this, mixed): $this`), inferred closure parameters now resolve to the receiver class rather than the class the user is editing. Previously, `Builder::when(true, function ($query) { $query-> })` inside a controller would infer `$query` as the controller class. Now it correctly resolves to the Builder. Works for instance method calls, static method calls, and arrow functions.
 - **Inline array element function calls.** `end($customers)->`, `current($this->users)->`, and similar inline uses of array element-extracting functions (`end`, `current`, `reset`, `next`, `prev`, `array_pop`, `array_shift`) now resolve to the element type. Previously this only worked when the result was assigned to a variable (`$last = end($customers); $last->`). The resolver now detects known array functions in the inline call path, resolves the first argument's iterable type (supporting plain variables with docblock/assignment scanning, call chains like `Customer::get()->all()`, static calls, and property access), extracts the generic element type, and returns the corresponding class.
 - **Generator TSend inference inside nested control flow.** `$var = yield $expr` inside `while`, `if`, `foreach`, or other nested blocks now correctly resolves `$var` to the TSend type from the enclosing generator's `@return Generator<TKey, TValue, TSend, TReturn>` annotation. Previously `find_enclosing_return_type` was called with the cursor offset, so its backward brace scan stopped at the innermost block's `{` (e.g. the `if`'s opening brace) instead of reaching the function's opening brace. The call now uses the method/function body's opening brace offset directly from the AST, which is immune to intermediate control-flow braces. Yield-based TValue inference (`yield $var`) was already unaffected because the text-based body scan operates on the full function body.
 - **Callable parameter type parsing in union types.** `extract_callable_param_types` now handles callable signatures wrapped in unions like `(Closure(Builder<TModel>): mixed)|null`, `callable(Collection<int, TValue>, int): mixed|null`, and `null|callable(Order): bool`. Previously the parser treated the entire union as one token and failed to find the callable signature. The `split_type_token` tokenizer was also fixed to keep generic suffixes like `Collection<int, User>|null` and parenthesized groups like `(Closure(X): Y)|null` as single tokens instead of splitting at the closing `>`, `}`, or `)`. This enables closure parameter inference for Laravel methods like `Builder::whereHas()`, `BuildsQueries::chunk()`, and `Builder::with()`, where the callback parameter types use these union patterns.

docs/todo-laravel.md

@@ -73,43 +73,7 @@ benefit) and an **Effort** estimate (implementation complexity):
 
 ---
 
-#### 1. `$this` in inferred callable parameter types resolves to wrong class
-
-| | |
-|---|---|
-| **Impact** | ★★ — Manifests only when closure params are untyped; most IDE-aware codebases type-hint explicitly. Affects `when()`, `tap()`, and similar higher-order Eloquent/Collection methods. |
-| **Effort** | ★ — Replace literal `$this`/`static` tokens with the receiver's FQN in `infer_callable_params_from_receiver` before returning. |
-
-When a closure parameter is untyped and the inference system extracts
-callable param types from the called method's signature, `$this` in
-the extracted type resolves to the **calling class** (the class
-containing the user's code) instead of the class that declares the
-method.
-
-```php
-// Builder::when() signature (from Conditionable trait):
-// @param callable($this, mixed): $this $callback
-
-// In a controller:
-User::when($active, function ($query) {
-    $query->  // $query inferred as Controller, not Builder<User>
-});
-```
-
-The callable param types are extracted as raw strings by
-`extract_callable_param_types`.  When `$this` appears in these
-strings, `resolve_closure_params_with_inferred` passes them to
-`type_hint_to_classes`, which resolves `$this` relative to
-`ctx.current_class` — the class the user is editing, not the class
-that owns the method.
-
-**Where to change:** In `infer_callable_params_from_receiver` (and
-the static variant), after extracting callable param types, replace
-any literal `$this` or `static` tokens with the FQN of the receiver
-class before returning them.  This ensures the inferred types
-reference the declaring class rather than the calling class.
-
-#### 2. `*_count` relationship count properties
+#### 1. `*_count` relationship count properties
 
 | | |
 |---|---|
@@ -135,7 +99,7 @@ again and push a `{snake_name}_count` property typed as `int` for
 each one.  The property should have lower priority than explicit
 `@property` tags.
 
-#### 3. `#[Scope]` attribute (Laravel 11+)
+#### 2. `#[Scope]` attribute (Laravel 11+)
 
 | | |
 |---|---|
@@ -165,7 +129,7 @@ methods with the `#[Scope]` attribute the same as `scopeX` methods
 (strip the first `$query` parameter, expose as both static and
 instance virtual methods).
 
-#### 4. `$dates` array (deprecated)
+#### 3. `$dates` array (deprecated)
 
 | | |
 |---|---|
@@ -184,7 +148,7 @@ Merge these into `casts_definitions` at a lower priority than explicit
 `$casts` entries, or add a separate field on `ClassInfo` and handle
 priority in the provider.
 
-#### 5. Custom Eloquent builders (`HasBuilder` / `#[UseEloquentBuilder]`)
+#### 4. Custom Eloquent builders (`HasBuilder` / `#[UseEloquentBuilder]`)
 
 | | |
 |---|---|
@@ -222,7 +186,7 @@ declares a custom builder via `@use HasBuilder<X>` in `use_generics`
 or a `newEloquentBuilder()` method with a non-default return type.
 If found, load and resolve that builder class instead.
 
-#### 6. `abort_if`/`abort_unless` type narrowing
+#### 5. `abort_if`/`abort_unless` type narrowing
 
 | | |
 |---|---|
@@ -266,7 +230,7 @@ to subsequent code:
 This is similar to the existing guard clause narrowing but triggered
 by specific function names rather than `if` + early return.
 
-#### 7. `collect()` and other helper functions lose generic type info
+#### 6. `collect()` and other helper functions lose generic type info
 
 | | |
 |---|---|
@@ -314,7 +278,7 @@ before passing it to `type_hint_to_classes`.  See the general TODO
 item (§ PHP Language Feature Gaps, "Function-level `@template`
 generic resolution") for the full implementation plan.
 
-#### 8. Factory `has*`/`for*` relationship methods
+#### 7. Factory `has*`/`for*` relationship methods
 
 | | |
 |---|---|
@@ -352,7 +316,7 @@ The `has*` variant should accept optional `int $count` and
 `array|callable $state` parameters; `for*` should accept
 `array|callable $state`.
 
-#### 9. `$pivot` property on BelongsToMany related models
+#### 8. `$pivot` property on BelongsToMany related models
 
 | | |
 |---|---|
@@ -398,7 +362,7 @@ the `BelongsToMany` relationship stubs. If the user's stub set
 includes these annotations, it already works through our PHPDoc
 provider.
 
-#### 10. `withSum()` / `withAvg()` / `withMin()` / `withMax()` aggregate properties
+#### 9. `withSum()` / `withAvg()` / `withMin()` / `withMax()` aggregate properties
 
 | | |
 |---|---|
@@ -414,7 +378,7 @@ aggregate function (`withSum`/`withAvg` → `float`,
 
 The `@property` workaround applies here too.
 
-#### 11. Higher-order collection proxies
+#### 10. Higher-order collection proxies
 
 | | |
 |---|---|
@@ -437,7 +401,7 @@ and `HigherOrderCollectionProxyExtension`, which resolve the proxy's
 template types and delegate property/method lookups to the collection's
 value type.
 
-#### 12. `SoftDeletes` trait methods on Builder
+#### 11. `SoftDeletes` trait methods on Builder
 
 | | |
 |---|---|
@@ -465,7 +429,7 @@ type — e.g. `Builder<static>` instead of `Builder<User>`.  This is
 a minor gap but not worth a dedicated fix until custom builder
 support (gap §7) is implemented.
 
-#### 13. `View::withX()` and `RedirectResponse::withX()` dynamic methods
+#### 12. `View::withX()` and `RedirectResponse::withX()` dynamic methods
 
 | | |
 |---|---|
@@ -497,7 +461,7 @@ 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.
 
-#### 14. `$appends` array
+#### 13. `$appends` array
 
 | | |
 |---|---|

example.php

@@ -1259,6 +1259,15 @@ public function demo(): void
         BlogAuthor::whereHas('posts', function ($query) {
             $query->where('published', true); // resolves to Builder
         });
+
+        // $this in callable param resolves to receiver, not current class
+        $pipeline = new ScaffoldingPipeline();
+        $pipeline->when(true, function ($pipe) {
+            $pipe->send('data');          // resolves to ScaffoldingPipeline, not this demo class
+        });
+
+        // Arrow function variant
+        $pipeline->tap(fn($p) => $p->through([]));
     }
 }
 
@@ -1793,6 +1802,24 @@ class ScaffoldingClosureParamInference
     public FluentCollection $items;
 }
 
+class ScaffoldingPipeline
+{
+    /**
+     * @param callable($this, mixed): $this $callback
+     * @return $this
+     */
+    public function when(bool $condition, callable $callback): static { return $this; }
+
+    /**
+     * @param callable($this): void $callback
+     * @return $this
+     */
+    public function tap(callable $callback): static { return $this; }
+
+    public function send(mixed $data): static { return $this; }
+    public function through(array $pipes): static { return $this; }
+}
+
 class ScaffoldingFirstClassCallable
 {
     public function dispatch(): Pen

src/completion/closure_resolution.rs

@@ -662,7 +662,17 @@ impl Backend {
         let rctx = ctx.as_resolution_ctx();
         let receiver_classes = Self::resolve_target_classes(obj_text, AccessKind::Arrow, &rctx);
 
-        Self::find_callable_params_on_classes(&receiver_classes, method_name, arg_idx, ctx)
+        let params =
+            Self::find_callable_params_on_classes(&receiver_classes, method_name, arg_idx, ctx);
+
+        // Replace `$this` / `static` tokens with the receiver class FQN
+        // so that `resolve_closure_params_with_inferred` resolves them
+        // against the declaring class rather than the user's current class.
+        if let Some(receiver) = receiver_classes.first() {
+            Self::replace_self_references(params, &receiver.name)
+        } else {
+            params
+        }
     }
 
     /// Infer callable parameter types for a closure passed at position
@@ -689,12 +699,75 @@ impl Backend {
         });
         if let Some(ref cls) = owner {
             let resolved = Self::resolve_class_fully(cls, ctx.class_loader);
-            Self::find_callable_params_on_method(&resolved, method_name, arg_idx, ctx)
+            let params = Self::find_callable_params_on_method(&resolved, method_name, arg_idx, ctx);
+            Self::replace_self_references(params, &cls.name)
         } else {
             vec![]
         }
     }
 
+    /// Replace `$this` and `static` tokens in inferred callable parameter
+    /// type strings with the given class FQN.  This ensures that when a
+    /// method signature uses `$this` or `static` (e.g.
+    /// `callable($this): $this`), the inferred types reference the
+    /// declaring/receiver class rather than the class the user is editing.
+    fn replace_self_references(params: Vec<String>, class_fqn: &str) -> Vec<String> {
+        params
+            .into_iter()
+            .map(|ty| {
+                // Replace whole-word occurrences of `$this` and `static`.
+                // These appear as standalone type tokens in callable
+                // signatures, e.g. `callable($this, mixed): $this`.
+                let result = ty.as_str();
+                // Fast path: nothing to replace.
+                if !result.contains("$this") && !result.contains("static") {
+                    return ty;
+                }
+                let mut out = String::with_capacity(result.len());
+                let mut rest = result;
+                while !rest.is_empty() {
+                    if let Some(pos) = rest.find("$this") {
+                        // Check that it's a word boundary (not part of a
+                        // longer identifier).
+                        let after = pos + 5;
+                        let is_boundary =
+                            after >= rest.len() || !rest.as_bytes()[after].is_ascii_alphanumeric();
+                        if is_boundary {
+                            out.push_str(&rest[..pos]);
+                            out.push_str(class_fqn);
+                            rest = &rest[after..];
+                            continue;
+                        }
+                        // Not a boundary — consume past this occurrence.
+                        out.push_str(&rest[..after]);
+                        rest = &rest[after..];
+                        continue;
+                    }
+                    if let Some(pos) = rest.find("static") {
+                        let before_ok =
+                            pos == 0 || !rest.as_bytes()[pos - 1].is_ascii_alphanumeric();
+                        let after = pos + 6;
+                        let after_ok =
+                            after >= rest.len() || !rest.as_bytes()[after].is_ascii_alphanumeric();
+                        if before_ok && after_ok {
+                            out.push_str(&rest[..pos]);
+                            out.push_str(class_fqn);
+                            rest = &rest[after..];
+                            continue;
+                        }
+                        out.push_str(&rest[..after]);
+                        rest = &rest[after..];
+                        continue;
+                    }
+                    // No more occurrences.
+                    out.push_str(rest);
+                    break;
+                }
+                out
+            })
+            .collect()
+    }
+
     /// Search for the method `method_name` on each of `classes` and
     /// extract callable parameter types at `arg_idx`.
     fn find_callable_params_on_classes(