Callable parameter type parsing in union types

Author: AJenbo

docs/CHANGELOG.md

@@ -45,6 +45,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **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.
 - **Blank lines inside method chains no longer break resolution.** A blank (or whitespace-only) line between segments of a fluent chain (e.g. `Brand::with('english')\n\n    ->paginate()`) caused the backward walk in `collapse_continuation_lines` to stop prematurely, treating the empty line as the base expression. Neither completion nor go-to-definition worked in this case. The backward walk now skips blank lines, and the collapsed result omits them, so chains with cosmetic spacing resolve correctly.
 - **Arrow function parameter go-to-definition.** Go-to-definition on a variable used in an arrow function body (e.g. `$o` in `fn(Order $o) => $o->getItems()`) now jumps to the parameter on the same line. Previously the backward scan excluded the cursor line, so it would skip the arrow function parameter and jump to an unrelated earlier variable with the same name. The fix includes the cursor line in the scan but only accepts non-assignment definitions (parameters, foreach, catch, static/global) to preserve the existing behavior for reassignments like `$value = $value->value`. Go-to-definition on the parameter itself (the LHS `$o`) correctly resolves the type hint and jumps to the `Order` class.
 - **Relationship property collection type uses the related model's custom collection.** When a model like `Product` had a `HasMany<Review, $this>` relationship, the virtual property `$product->reviews` incorrectly used the owning model's custom collection (`ProductCollection`) instead of the related model's (`ReviewCollection`). The provider now loads the related model via `class_loader` and reads its `custom_collection` field. The integration test was updated to use distinct collections per model so the bug is no longer masked.

docs/todo-laravel.md

@@ -8,21 +8,6 @@ virtual member provider design, see `ARCHITECTURE.md`.
 
 ---
 
-## Missing features
-
-### 2. Closure parameter inference in collection pipelines
-
-`$users->map(fn($u) => $u->...)` does not infer `$u` as the
-collection's element type. This is a general generics/callable
-inference problem, not Laravel-specific, but Laravel collection
-pipelines are the most common place users encounter it.
-Other cases:
-- MyModel::whereIn()->chunk(self::CHUNK_SIZE, function (Collection $orders) {})
-- MyModel::whereHas('order', function (Builder $q) {})
-- MyModel::with(['translations' => function (Relation $query) {}]) // translations is the name of the relation on MyModel, Relation will become the return type of that relation
-
----
-
 ## Out of scope (and why)
 
 | Item | Reason |

example.php

@@ -1779,6 +1779,24 @@ public function explicitTypeWins(): void
         // Explicit type hint takes precedence over inference.
         $this->users->map(fn(Order $o) => $o->customer);
     }
+
+    public function chunkInference(): void
+    {
+        // $orders is inferred as Collection from chunk's
+        // callable(Collection<int, TModel>, int) signature.
+        \App\Models\BlogAuthor::where('active', true)->chunk(100, function ($orders) {
+            $orders->count();             // resolves to Eloquent Collection
+        });
+    }
+
+    public function whereHasInference(): void
+    {
+        // $q is inferred as Builder from whereHas's
+        // Closure(Builder<TModel>): mixed signature.
+        \App\Models\BlogAuthor::whereHas('posts', function ($q) {
+            $q->where('published', true); // resolves to Builder
+        });
+    }
 }
 
 
@@ -2878,6 +2896,20 @@ public function where($column, $operator = null, $value = null, $boolean = 'and'
 
         /** @return \Illuminate\Database\Eloquent\Collection<int, TModel> */
         public function get($columns = ['*']) { return new Collection(); }
+
+        /**
+         * @param  string  $relation
+         * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TModel>): mixed)|null  $callback
+         * @return static
+         */
+        public function whereHas(string $relation, ?\Closure $callback = null): static { return $this; }
+
+        /**
+         * @param  array<array-key, array|(\Closure(\Illuminate\Database\Eloquent\Relations\Relation): mixed)|string>|string  $relations
+         * @param  (\Closure(\Illuminate\Database\Eloquent\Relations\Relation): mixed)|string|null  $callback
+         * @return static
+         */
+        public function with($relations, $callback = null): static { return $this; }
     }
 
     /**
@@ -2892,6 +2924,17 @@ public function count(): int { return 0; }
 }
 
 namespace Illuminate\Database\Eloquent\Relations {
+    /**
+     * @template TRelated of \Illuminate\Database\Eloquent\Model
+     * @template TDeclaringModel of \Illuminate\Database\Eloquent\Model
+     * @template TResult
+     */
+    class Relation {
+        /** @return static */
+        public function where(string $column, $operator = null, $value = null): static { return $this; }
+        /** @return static */
+        public function orderBy(string $column, string $direction = 'asc'): static { return $this; }
+    }
     class HasMany {}
     class HasOne {}
     class BelongsTo {}
@@ -2924,6 +2967,12 @@ trait HasCollection {}
     trait BuildsQueries {
         /** @return TValue|null */
         public function first($columns = ['*']) { return null; }
+
+        /**
+         * @param  callable(\Illuminate\Support\Collection<int, TValue>, int): mixed  $callback
+         * @return bool
+         */
+        public function chunk(int $count, callable $callback): bool { return true; }
     }
 }
 
@@ -2952,6 +3001,27 @@ public function get($columns = ['*']) {}
     }
 }
 
+namespace Illuminate\Support {
+
+    /**
+     * @template TKey of array-key
+     * @template TValue
+     */
+    class Collection {
+        /** @return int */
+        public function count(): int { return 0; }
+        /** @return TValue|null */
+        public function first(): mixed { return null; }
+        /** @return array<TKey, TValue> */
+        public function all(): array { return []; }
+        /**
+         * @param callable(TValue, TKey): mixed $callback
+         * @return static
+         */
+        public function each(callable $callback): static { return $this; }
+    }
+}
+
 namespace Illuminate\Contracts\Database\Eloquent {
     /**
      * @mixin \Illuminate\Database\Eloquent\Builder

src/docblock/types.rs

@@ -53,8 +53,11 @@ pub(crate) fn split_type_token(s: &str) -> (&str, &str) {
                 angle_depth -= 1;
                 // If we just closed the outermost `<`, the type ends here
                 // (but only when we're not also inside braces or parens).
+                // Continue consuming any union/intersection suffix so
+                // that `Collection<int, User>|null` stays one token.
                 if angle_depth == 0 && brace_depth == 0 && paren_depth == 0 {
                     let end = i + c.len_utf8();
+                    let end = consume_union_intersection_suffix(s, end);
                     return (&s[..end], &s[end..]);
                 }
             }
@@ -63,8 +66,11 @@ pub(crate) fn split_type_token(s: &str) -> (&str, &str) {
                 brace_depth -= 1;
                 // If we just closed the outermost `{`, the type ends here
                 // (but only when we're not also inside angle brackets or parens).
+                // Continue consuming any union/intersection suffix so
+                // that `array{id: int}|null` stays one token.
                 if brace_depth == 0 && angle_depth == 0 && paren_depth == 0 {
                     let end = i + c.len_utf8();
+                    let end = consume_union_intersection_suffix(s, end);
                     return (&s[..end], &s[end..]);
                 }
             }
@@ -91,12 +97,24 @@ pub(crate) fn split_type_token(s: &str) -> (&str, &str) {
                             let ret_start_in_s = colon_start_in_s
                                 + (after_colon.as_ptr() as usize
                                     - s[colon_start_in_s..].as_ptr() as usize);
-                            let end = ret_start_in_s + ret_tok.len();
+                            let mut end = ret_start_in_s + ret_tok.len();
+
+                            // After a callable return type, continue
+                            // consuming union/intersection suffixes so
+                            // that `(Closure(Builder): mixed)|null`
+                            // is kept as one token.
+                            end = consume_union_intersection_suffix(s, end);
+
                             return (&s[..end], &s[end..]);
                         }
                     }
-                    // No return type — the token ends here (e.g. bare `callable(int)`).
-                    return (&s[..after_paren], &s[after_paren..]);
+                    // After a bare parenthesized group (no callable
+                    // return type), continue consuming any
+                    // union/intersection suffix.  This handles DNF
+                    // types like `(A&B)|C` and grouped callables
+                    // like `(Closure(X): Y)|null`.
+                    let end = consume_union_intersection_suffix(s, after_paren);
+                    return (&s[..end], &s[end..]);
                 }
             }
             c if c.is_whitespace() && angle_depth == 0 && brace_depth == 0 && paren_depth == 0 => {
@@ -109,6 +127,46 @@ pub(crate) fn split_type_token(s: &str) -> (&str, &str) {
     (s, "")
 }
 
+/// After a parenthesized type group or callable return type, consume
+/// any `|Type` or `&Type` continuation so the full union/intersection
+/// is kept as a single token.
+///
+/// `pos` is the byte offset just past the already-consumed portion of
+/// `s`.  Returns the updated end offset after consuming zero or more
+/// `|`/`&`-separated type parts.
+fn consume_union_intersection_suffix(s: &str, pos: usize) -> usize {
+    let mut end = pos;
+    loop {
+        let rest = &s[end..];
+        // Allow optional whitespace before the operator, but only if
+        // the operator is `|` or `&` (not a plain space which would
+        // signal the start of the next token like a parameter name).
+        let rest_trimmed = rest.trim_start();
+        let first = rest_trimmed.chars().next();
+        if first == Some('|') || first == Some('&') {
+            // Skip the operator character.
+            let after_op = &rest_trimmed[1..];
+            let after_op = after_op.trim_start();
+            if after_op.is_empty() {
+                break;
+            }
+            // Consume the next type token.
+            let (tok, _) = split_type_token(after_op);
+            if tok.is_empty() {
+                break;
+            }
+            // Compute the absolute end position from the consumed
+            // token.  `after_op` is a sub-slice of `s`, so pointer
+            // arithmetic gives us the byte offset.
+            let tok_start_in_s = after_op.as_ptr() as usize - s.as_ptr() as usize;
+            end = tok_start_in_s + tok.len();
+        } else {
+            break;
+        }
+    }
+    end
+}
+
 /// Split a type string on `|` at nesting depth 0, respecting `<…>`,
 /// `(…)`, and `{…}` nesting.
 ///
@@ -991,6 +1049,34 @@ pub fn extract_callable_return_type(type_str: &str) -> Option<String> {
 /// string                          → None
 /// ```
 pub fn extract_callable_param_types(type_str: &str) -> Option<Vec<String>> {
+    // Unwrap union types: `(Closure(X): Y)|null` → `Closure(X): Y`,
+    // `Closure(X): Y|null` → try `Closure(X): Y|null` first, then
+    // fall back to splitting on `|` and trying each part.
+    if let Some(result) = extract_callable_param_types_inner(type_str) {
+        return Some(result);
+    }
+
+    // Try each union member individually — handles `Closure(X)|null`,
+    // `null|callable(Y)`, and parenthesized groups like
+    // `(Closure(X): Y)|null`.
+    for part in split_union_depth0(type_str) {
+        let part = part.trim();
+        // Strip outer parens from grouped callables: `(Closure(X): Y)` → `Closure(X): Y`
+        let inner = part
+            .strip_prefix('(')
+            .and_then(|p| p.strip_suffix(')'))
+            .unwrap_or(part);
+        if let Some(result) = extract_callable_param_types_inner(inner) {
+            return Some(result);
+        }
+    }
+
+    None
+}
+
+/// Inner implementation: try to parse a single callable/Closure type
+/// string (not a union) and extract its parameter types.
+fn extract_callable_param_types_inner(type_str: &str) -> Option<Vec<String>> {
     let s = type_str.strip_prefix('\\').unwrap_or(type_str);
     let s = s.strip_prefix('?').unwrap_or(s);
 

tests/completion_closure_param_inference.rs

@@ -625,3 +625,65 @@ fn test_extract_callable_param_types_array_shape() {
         Some(vec!["array{name: string, age: int}".to_string()]),
     );
 }
+
+#[test]
+fn test_extract_callable_param_types_union_with_null() {
+    use phpantom_lsp::docblock::extract_callable_param_types;
+
+    // `Closure(Builder): mixed|null` — union at the top level
+    assert_eq!(
+        extract_callable_param_types("Closure(Builder): mixed|null"),
+        Some(vec!["Builder".to_string()]),
+    );
+
+    // `callable(User): void|null`
+    assert_eq!(
+        extract_callable_param_types("callable(User): void|null"),
+        Some(vec!["User".to_string()]),
+    );
+
+    // `null|callable(Order): bool`
+    assert_eq!(
+        extract_callable_param_types("null|callable(Order): bool"),
+        Some(vec!["Order".to_string()]),
+    );
+}
+
+#[test]
+fn test_extract_callable_param_types_parenthesized_group() {
+    use phpantom_lsp::docblock::extract_callable_param_types;
+
+    // `(Closure(Builder<Brand>): mixed)|null` — parenthesized callable in union
+    assert_eq!(
+        extract_callable_param_types("(Closure(Builder<Brand>): mixed)|null"),
+        Some(vec!["Builder<Brand>".to_string()]),
+    );
+
+    // `(\\Closure(\\App\\Models\\User): mixed)|string|null`
+    assert_eq!(
+        extract_callable_param_types("(\\Closure(\\App\\Models\\User): mixed)|string|null"),
+        Some(vec!["\\App\\Models\\User".to_string()]),
+    );
+}
+
+#[test]
+fn test_extract_callable_param_types_parenthesized_no_union() {
+    use phpantom_lsp::docblock::extract_callable_param_types;
+
+    // Bare parenthesized callable without union suffix
+    assert_eq!(
+        extract_callable_param_types("(Closure(Config): void)"),
+        Some(vec!["Config".to_string()]),
+    );
+}
+
+#[test]
+fn test_extract_callable_param_types_union_non_callable_parts() {
+    use phpantom_lsp::docblock::extract_callable_param_types;
+
+    // Union where no part is a callable — should return None
+    assert_eq!(extract_callable_param_types("string|null"), None,);
+
+    // Union with a class name but no callable signature
+    assert_eq!(extract_callable_param_types("Closure|null"), None,);
+}