Fix closure param inference for function-level templates and property

chains

Author: AJenbo

docs/CHANGELOG.md

@@ -56,6 +56,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Closure parameter inference from function-level `@template` bindings.** Functions like `array_any`, `array_all`, and `array_find` that declare `@template` parameters bound through an array parameter and used in a `callable` parameter now infer concrete types for untyped closure arguments. For example, `array_any($this->items, fn($item) => $item->name !== '')` where `$this->items` is `array<int, Product>` now resolves `$item` as `Product`. Previously `$item` was unresolved, producing false-positive `unresolved_member_access` diagnostics. This also fixes a related issue where `@param` tags in phpstorm-stubs that omit the parameter name (e.g. `@param callable(TValue, TKey): bool` without `$callback`) failed to enrich the parameter's type hint, preventing callable parameter type extraction.
+- **Property chain arguments in template substitution.** Expressions like `$this->items` or `$obj->prop` passed as arguments to templated functions now resolve their type for template binding. Previously only bare variables (e.g. `$items`) were resolved, so `array_any($this->items, fn($x) => ...)` could not infer the element type even when the property had a fully substituted generic type.
 - **Variable reassignment inside `try` blocks now tracked by the analyzer.** When a variable was reassigned to a different type inside a `try` block, subsequent accesses within the same block still resolved against the original type, producing false-positive `unknown_member` diagnostics. The same applied to `catch` and `finally` blocks. Assignments preceding the cursor within the same block are now treated as sequential.
 - **Types with `covariant` or `contravariant` variance annotations in generic args now parse correctly.** PHPStan/Larastan annotations like `BelongsTo<Category, covariant $this>` previously failed to parse, causing the entire type to become unresolvable. This broke Eloquent relationship property synthesis (virtual properties were not generated when the `@return` annotation used variance modifiers) and member lookup on relationship method return types (e.g. `$model->category()->associate()` reported `associate()` as not found). The variance keywords are now stripped from generic parameter positions before parsing.
 - **Diagnostics now work for vendor files open in the editor.** Projects using `--prefer-source` or monorepo setups where libraries are edited from the `vendor/` directory no longer have diagnostics suppressed. Previously all vendor files were unconditionally skipped, hiding syntax errors, deprecation warnings, and all other diagnostics. The `analyze` command also accepts vendor paths as explicit overrides (e.g. `phpantom_lsp analyze vendor/some-package/src/`).

docs/todo.md

@@ -23,7 +23,6 @@ within the same impact tier.
 
 | #   | Item                                                                                                                                             | Impact | Effort |
 | --- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ------ |
-| B5  | [`$this->items` on custom Collection subclass not typed](todo/bugs.md#b5-thisitems-on-custom-collection-subclass-not-typed)                      | Low    | Medium |
 | B6  | [Scope methods not found on Builder in analyzer chains](todo/bugs.md#b6-scope-methods-not-found-on-builder-in-analyzer-chains)                   | High   | Medium |
 | B7  | [PHPDoc `@param` generic array type not merged with native `array` hint](todo/bugs.md#b7-phpdoc-param-generic-array-type-not-merged-with-native-array-hint) | Low | Medium |
 | B8  | [Variadic parameter element type lost in `foreach`](todo/bugs.md#b8-variadic-parameter-element-type-lost-in-foreach)                             | Low    | Low    |

docs/todo/bugs.md

@@ -1,38 +1,5 @@
 # PHPantom — Bug Fixes
 
-## B5: `$this->items` on custom Collection subclass not typed
-
-When a class extends `Collection<int, T>` via `@extends`, accessing
-`$this->items` should yield `array<int, T>`. Currently, `$this->items`
-resolves as `array` (the base `Collection`'s declared property type)
-without applying the generic substitution. This means iterating
-`$this->items` in a `foreach` or passing it to `array_any()` loses the
-element type.
-
-Real-world example — `PurchaseFileProductCollection.php`:
-
-```php
-/**
- * @extends Collection<int, PurchaseFileProduct>
- */
-final class PurchaseFileProductCollection extends Collection
-{
-    public function hasIssues(): bool
-    {
-        return array_any($this->items, fn($item) => $item->order_amount > 0);
-        //                                          ^^^^^ unresolved
-    }
-}
-```
-
-`$this->items` should be `array<int, PurchaseFileProduct>`, so `$item`
-in the closure should be `PurchaseFileProduct`. Instead, `$item` is
-unresolved because the generic substitution is not applied to inherited
-properties when accessed via `$this->`.
-
-**Impact:** 2 diagnostics in the shared project
-(`PurchaseFileProductCollection:25` — two property accesses on `$item`).
-
 ## B6: Scope methods not found on Builder in analyzer chains
 
 PHPantom's completion engine correctly injects scope methods onto
@@ -161,4 +128,4 @@ case-insensitive matching) when looking up relationship-derived virtual
 properties on Eloquent models.
 
 **Impact:** 1 direct diagnostic (`FlowService:477`) plus 1 cascading
-(`FlowService:517` — compound with `Collection::reduce()` type loss).
+(`FlowService:517` — compound with `Collection::reduce()` type loss).

example.php

@@ -1772,6 +1772,12 @@ public function demo(): void
 
         // Arrow function variant
         $pipeline->tap(fn($p) => $p->through([]));
+
+        // Function-level @template callable inference
+        // array_any(@param array<TKey, TValue>, @param callable(TValue, TKey): bool)
+        // $item is inferred as Pen from the array's element type via template substitution
+        $holder = new ScaffoldingTemplateCallableHolder();
+        array_any($holder->tools, fn($item) => $item->write() !== '');
     }
 }
 
@@ -3497,6 +3503,12 @@ class ScaffoldingClosureParamInference
     public function __construct() { $this->items = new FluentCollection([new Pen('red'), new Pen('blue')]); }
 }
 
+class ScaffoldingTemplateCallableHolder
+{
+    /** @var array<int, Pen> */
+    public array $tools = [];
+}
+
 /**
  * @template TValue
  */
@@ -5305,6 +5317,12 @@ function runDemoAssertions(): void
     });
     assert(count($closureReceived) === 2, 'each() must invoke callback for every item');
 
+    // Function-level @template callable inference (array_any pattern)
+    $tplHolder = new ScaffoldingTemplateCallableHolder();
+    $tplHolder->tools = [new Pen('red'), new Pen('blue')];
+    $tplResult = array_any($tplHolder->tools, fn($t) => $t->color() === 'red');
+    assert($tplResult === true, 'array_any with template callable must work');
+
     // ── Type alias resolution ───────────────────────────────────────────
     $aliasDemo = new TypeAliasDemo();
     $userData = $aliasDemo->getUserData();

src/completion/variable/closure_resolution.rs

@@ -994,7 +994,14 @@ fn try_resolve_in_closure_call<'b>(
                     &fc.argument_list.arguments,
                     ctx,
                     results,
-                    |arg_idx| infer_callable_params_from_function(&func_name, arg_idx, ctx),
+                    |arg_idx| {
+                        infer_callable_params_from_function(
+                            &func_name,
+                            arg_idx,
+                            &fc.argument_list.arguments,
+                            ctx,
+                        )
+                    },
                 )
             {
                 return true;
@@ -1429,9 +1436,17 @@ fn extract_function_name_from_call(fc: &FunctionCall<'_>) -> Option<String> {
 
 /// Infer callable parameter types for a closure passed at position
 /// `arg_idx` to a standalone function call.
+///
+/// When the function has `@template` parameters (e.g.
+/// `array_any(array<TKey, TValue> $array, callable(TValue, TKey): bool $cb)`),
+/// the template substitution map is built from the other call-site
+/// arguments and applied to the callable's parameter types.  This turns
+/// raw template names like `TValue` into concrete types like
+/// `PurchaseFileProduct`.
 fn infer_callable_params_from_function(
     func_name: &str,
     arg_idx: usize,
+    arguments: &TokenSeparatedSequence<'_, argument::Argument<'_>>,
     ctx: &VarResolutionCtx<'_>,
 ) -> Vec<String> {
     let rctx = ctx.as_resolution_ctx();
@@ -1441,12 +1456,61 @@ fn infer_callable_params_from_function(
         None
     };
     if let Some(fi) = func_info {
-        extract_callable_params_at(&fi.parameters, arg_idx, ctx)
+        let mut params = extract_callable_params_at(&fi.parameters, arg_idx, ctx);
+
+        // When the function has template parameters, build a
+        // substitution map from the concrete call-site arguments and
+        // apply it to the extracted callable param types.  Without
+        // this, functions like `array_any($this->items, fn($item) => …)`
+        // would pass raw template names (`TValue`) instead of the
+        // concrete element type (`PurchaseFileProduct`).
+        if !params.is_empty() && !fi.template_params.is_empty() && !fi.template_bindings.is_empty()
+        {
+            let text_args = extract_argument_texts(arguments, ctx.content);
+            let text_args_joined = text_args.join(", ");
+            let subs =
+                super::rhs_resolution::build_function_template_subs(&fi, &text_args_joined, &rctx);
+            if !subs.is_empty() {
+                params = params
+                    .into_iter()
+                    .map(|p| {
+                        let substituted = crate::inheritance::apply_substitution(&p, &subs);
+                        substituted.into_owned()
+                    })
+                    .collect();
+            }
+        }
+
+        params
     } else {
         vec![]
     }
 }
 
+/// Extract the source text of each positional argument in a call's
+/// argument list.
+fn extract_argument_texts(
+    arguments: &TokenSeparatedSequence<'_, argument::Argument<'_>>,
+    content: &str,
+) -> Vec<String> {
+    arguments
+        .iter()
+        .map(|arg| {
+            let span = match arg {
+                argument::Argument::Positional(pos) => pos.value.span(),
+                argument::Argument::Named(named) => named.value.span(),
+            };
+            let start = span.start.offset as usize;
+            let end = span.end.offset as usize;
+            if end <= content.len() {
+                content[start..end].to_string()
+            } else {
+                String::new()
+            }
+        })
+        .collect()
+}
+
 /// Infer callable parameter types for a closure passed at position
 /// `arg_idx` to an instance method call whose receiver expression
 /// spans `[obj_start, obj_end)` in the source text.

src/completion/variable/rhs_resolution.rs

@@ -1035,6 +1035,32 @@ fn resolve_arg_variable_raw_type(
         return None;
     }
 
+    // ── Property chain: `$this->items`, `$obj->prop` ────────────
+    // When the argument is a property access chain, resolve the base
+    // object's type and look up the property's type hint.  This is
+    // needed for template substitution in calls like
+    // `array_any($this->items, fn($item) => …)` where `$this->items`
+    // is `array<int, PurchaseFileProduct>` after generic substitution.
+    if let Some(arrow_pos) = var_name.find("->") {
+        let base = &var_name[..arrow_pos];
+        let prop = &var_name[arrow_pos + 2..];
+        // Only handle simple single-level property access for now.
+        if !prop.is_empty() && !prop.contains("->") && !prop.contains('(') {
+            let base_classes = crate::completion::resolver::resolve_target_classes(
+                base,
+                crate::types::AccessKind::Arrow,
+                rctx,
+            );
+            for cls in &base_classes {
+                if let Some(hint) =
+                    crate::inheritance::resolve_property_type_hint(cls, prop, rctx.class_loader)
+                {
+                    return Some(hint.to_string());
+                }
+            }
+        }
+    }
+
     // 1. Try docblock annotation (@var).
     if let Some(raw) = crate::docblock::find_iterable_raw_type_in_source(
         rctx.content,

src/diagnostics/unknown_members.rs

@@ -5035,4 +5035,67 @@ class Handler {
             "expected no diagnostics for reassigned variable inside catch block, got: {diags:?}"
         );
     }
+
+    #[test]
+    fn no_diagnostic_for_this_items_on_generic_collection_subclass() {
+        // B5: When a class extends `Collection<int, T>` via `@extends`,
+        // accessing `$this->items` should yield `array<int, T>` with the
+        // generic substitution applied.  Iterating `$this->items` in a
+        // `foreach` or passing it to `array_any()` should resolve the
+        // element type so that property access on `$item` works.
+        let php = r#"<?php
+/**
+ * @template TKey
+ * @template TValue
+ */
+class Collection {
+    /** @var array<TKey, TValue> */
+    public array $items = [];
+
+    /** @return TValue|null */
+    public function first(): mixed { return null; }
+}
+
+class PurchaseFileProduct {
+    public int $order_amount = 0;
+    public string $name = '';
+}
+
+/**
+ * @template TKey
+ * @template TValue
+ * @param array<TKey, TValue> $array
+ * @param callable(TValue, TKey): bool $callback
+ * @return bool
+ */
+function array_any(array $array, callable $callback): bool { return false; }
+
+/**
+ * @extends Collection<int, PurchaseFileProduct>
+ */
+final class PurchaseFileProductCollection extends Collection {
+    public function hasIssues(): bool {
+        return array_any($this->items, fn($item) => $item->order_amount > 0);
+    }
+
+    public function hasName(): bool {
+        return array_any($this->items, fn($item) => $item->name !== '');
+    }
+
+    public function foreachWorks(): void {
+        foreach ($this->items as $item) {
+            $item->order_amount;
+            $item->name;
+        }
+    }
+}
+"#;
+        let backend = Backend::new_test();
+        backend.config.lock().diagnostics.unresolved_member_access = Some(true);
+        let diags = collect(&backend, "file:///test.php", php);
+        assert!(
+            diags.is_empty(),
+            "expected no diagnostics for $this->items on generic Collection subclass, got: {diags:?}"
+        );
+    }
 }

src/docblock/mod.rs

@@ -51,14 +51,15 @@ pub use tags::{
     extract_mixin_tags, extract_mixin_tags_from_info, extract_param_closure_this,
     extract_param_closure_this_from_info, extract_param_description,
     extract_param_description_from_info, extract_param_raw_type, extract_param_raw_type_from_info,
-    extract_removed_version, extract_return_description, extract_return_description_from_info,
-    extract_return_type, extract_return_type_from_info, extract_see_references,
-    extract_see_references_from_info, extract_throws_tags, extract_throws_tags_from_info,
-    extract_type_assertions, extract_type_assertions_from_info, extract_var_type,
-    extract_var_type_from_info, extract_var_type_with_name, extract_var_type_with_name_from_info,
-    find_enclosing_return_type, find_inline_var_docblock, find_iterable_raw_type_in_source,
-    find_var_raw_type_in_source, get_docblock_info_for_node, get_docblock_text_for_node,
-    has_deprecated_tag, has_deprecated_tag_from_info, resolve_effective_type, should_override_type,
+    extract_param_types_positional_from_info, extract_removed_version, extract_return_description,
+    extract_return_description_from_info, extract_return_type, extract_return_type_from_info,
+    extract_see_references, extract_see_references_from_info, extract_throws_tags,
+    extract_throws_tags_from_info, extract_type_assertions, extract_type_assertions_from_info,
+    extract_var_type, extract_var_type_from_info, extract_var_type_with_name,
+    extract_var_type_with_name_from_info, find_enclosing_return_type, find_inline_var_docblock,
+    find_iterable_raw_type_in_source, find_var_raw_type_in_source, get_docblock_info_for_node,
+    get_docblock_text_for_node, has_deprecated_tag, has_deprecated_tag_from_info,
+    resolve_effective_type, should_override_type,
 };
 
 // Template / generics / type alias tags

src/docblock/tags.rs

@@ -645,6 +645,46 @@ pub fn extract_all_param_tags_from_info(info: &DocblockInfo) -> Vec<(String, Str
     results
 }
 
+/// Extract `@param` type strings in order of appearance, including
+/// tags that omit the parameter name.
+///
+/// Returns a list of `(Option<param_name>, type_string)` pairs in
+/// docblock order.  When a `@param` tag has no `$name` token (common
+/// in phpstorm-stubs, e.g. `@param callable(TValue, TKey): bool`),
+/// the first element is `None`.  Callers can match these entries to
+/// native parameters by position.
+///
+/// This is used as a positional fallback when name-based matching
+/// via [`extract_param_raw_type_from_info`] fails to find a docblock
+/// type for a parameter.
+pub fn extract_param_types_positional_from_info(
+    info: &DocblockInfo,
+) -> Vec<(Option<String>, String)> {
+    let mut results = Vec::new();
+
+    for tag in info.tags_by_kinds(&[TagKind::PhpstanParam, TagKind::Param]) {
+        let desc = tag.description.trim();
+        if desc.is_empty() {
+            continue;
+        }
+
+        let (type_token, remainder) = split_type_token(desc);
+
+        let param_name = remainder.split_whitespace().next().and_then(|name| {
+            let name = name.strip_prefix("...").unwrap_or(name);
+            if name.starts_with('$') {
+                Some(name.to_string())
+            } else {
+                None
+            }
+        });
+
+        results.push((param_name, type_token.to_string()));
+    }
+
+    results
+}
+
 /// Extract all `@param-closure-this` declarations from a docblock.
 ///
 /// The tag format is `@param-closure-this TypeName $paramName`, declaring