@implements generic resolution

Author: AJenbo

docs/CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Enum case properties.** Completing on an enum case variable (`$case->`) now shows `name` (on all enums) and `value` (on backed enums) inherited from the `UnitEnum` and `BackedEnum` interfaces.
+- **`@implements` generic resolution.** When a class declares `@implements SomeInterface<ConcreteType>`, template parameters on the interface's methods and properties are now substituted with the concrete types. Works with `@template-implements` and `@phpstan-implements` aliases, multiple `@implements` annotations on the same class, parameter type substitution (not just return types), and chained resolution through parent classes (e.g. `Test2 extends Test1<int>` where `Test1` has `@implements Iterator<TKey, string>`). Foreach iteration over classes implementing generic iterable interfaces (including through intermediate interface chains like `TypedCollection extends IteratorAggregate`) now resolves value and key types correctly.
 
 ### Fixed
 

docs/todo/testing.md

@@ -1,11 +1,11 @@
 # PHPantom — Ignored Fixture Tasks
 
-There are **228 fixture tests** in `tests/fixtures/`. Of these, **188
-pass** and **40 are ignored** because they exercise features or bug
+There are **228 fixture tests** in `tests/fixtures/`. Of these, **195
+pass** and **33 are ignored** because they exercise features or bug
 fixes that are not yet implemented. Each ignored fixture has a
 `// ignore:` comment explaining what is missing.
 
-This document groups the 40 ignored fixtures by the underlying work
+This document groups the 33 ignored fixtures by the underlying work
 needed to un-ignore them. Tasks are ordered by the number of fixtures
 they unblock (descending), then by estimated effort. Once a task is
 complete, remove the `// ignore:` line from each fixture, verify the
@@ -23,38 +23,6 @@ php -l example.php
 
 ---
 
-## 1. `@implements` generic resolution (7 fixtures)
-
-**Ref:** [type-inference.md §17](type-inference.md#17-implements-generic-resolution)
-**Impact: Medium-High · Effort: Medium**
-
-When a class declares `@implements SomeInterface<ConcreteType>`, the
-generic parameters are not substituted into inherited interface methods.
-This already works for `@extends` on classes, so the substitution
-infrastructure exists. The `@implements` path needs the same wiring.
-
-**Fixtures:**
-
-- [ ] `generics/class_implements_single.fixture` — `@implements Repo<User>` resolves `T` on method return
-- [ ] `generics/class_implements_multiple.fixture` — multiple `@implements` with different concrete types
-- [ ] `generics/class_template_implements.fixture` — `@template-implements` syntax (alias for `@implements`)
-- [ ] `generics/implements_parameter_type.fixture` — `@implements` resolves `T` on method parameters
-- [ ] `generics/iterator_aggregate_complex.fixture` — `@implements IteratorAggregate<Item>` for foreach
-- [ ] `generics/nested_iterator_chain_gh1875.fixture` — `@implements Iterator<Item>` through nested chain
-- [ ] `foreach/iterator_aggregate_key_value.fixture` — `@implements IteratorAggregate<K, V>` with key+value types
-
-**Implementation notes:**
-
-In `inheritance.rs`, `build_substitution_map` handles `@extends`
-annotations. Add the same logic for `@implements` annotations on the
-class. When merging interface methods in `resolve_class_fully_inner`
-(virtual_members), apply the substitution map from `@implements` to
-each inherited interface method's types. The `@template-implements`
-syntax should be treated as an alias, same as `@template-extends` is
-for `@extends`.
-
----
-
 ## 2. Function-level `@template` generic resolution (9 fixtures)
 
 **Ref:** [type-inference.md §2](type-inference.md#2-function-level-template-generic-resolution)

docs/todo/type-inference.md

@@ -584,40 +584,6 @@ type:
 
 ---
 
-## 17. `@implements` generic resolution
-**Impact: Medium-High · Effort: Medium**
-
-When a class declares `@implements SomeInterface<ConcreteType>`, the
-generic parameters should be substituted into inherited interface
-methods. This works for `@extends` on classes but the `@implements`
-path is not wired up.
-
-**Example:**
-
-```php
-/** @template T */
-interface Repository {
-    /** @return T */
-    public function find(int $id);
-}
-
-/** @implements Repository<User> */
-class UserRepository implements Repository {
-    public function find(int $id) { /* ... */ }
-}
-
-$repo = new UserRepository();
-$repo->find(1); // should resolve to User
-```
-
-A related variant is `@implements` through an extended interface chain
-with key+value types (e.g. `@implements IteratorAggregate<string, Item>`).
-
-**Discovered via:** fixture conversion (class_implements_single,
-class_implements_multiple, implements_parameter_type).
-
----
-
 ## 18. `@phpstan-assert` on static method calls
 **Impact: Medium · Effort: Medium**
 

example.php

@@ -305,6 +305,26 @@ public function demo(): void
 }
 
 
+// ── @implements Generic Resolution ─────────────────────────────────────────
+
+class ImplementsGenericDemo
+{
+    public function demo(): void
+    {
+        $repo = new PenStorage();
+        $repo->find(1)->write();                  // @implements Storage<Pen> → Pen
+
+        $penCatalog = new PenCatalog();
+        $penCatalog->find(1)->write();            // @template-implements alias
+
+        $items = new ItemIterableCollection();
+        foreach ($items as $item) {
+            $item->write();                       // @implements IteratorAggregate<Pen>
+        }
+    }
+}
+
+
 // ── Conditional Return Types ────────────────────────────────────────────────
 
 class ConditionalReturnDemo
@@ -2677,6 +2697,47 @@ class CachingPenRepository extends PenRepository
     public function clearCache(): void {}
 }
 
+// ─── @implements Generic Resolution ─────────────────────────────────────────
+
+/**
+ * @template TEntity
+ */
+interface Storage
+{
+    /** @return TEntity */
+    public function find(int $id);
+
+    /** @return TEntity[] */
+    public function findAll();
+}
+
+/** @implements Storage<Pen> */
+class PenStorage implements Storage
+{
+    public function find(int $id) { return new Pen(); }
+    public function findAll() { return [new Pen()]; }
+}
+
+/** @template-implements Storage<Pen> */
+class PenCatalog implements Storage
+{
+    public function find(int $id) { return new Pen(); }
+    public function findAll() { return [new Pen()]; }
+}
+
+/**
+ * @template T
+ * @implements \IteratorAggregate<int, T>
+ */
+class IterableCollection implements \IteratorAggregate
+{
+    /** @return \ArrayIterator<int, T> */
+    public function getIterator(): \ArrayIterator { return new \ArrayIterator([]); }
+}
+
+/** @extends IterableCollection<Pen> */
+class ItemIterableCollection extends IterableCollection {}
+
 /**
  * @template TKey of array-key
  * @template-covariant TValue

src/completion/call_resolution.rs

@@ -701,10 +701,17 @@ impl Backend {
 
         // First check the class itself
         if let Some(method) = class_info.methods.iter().find(|m| m.name == method_name) {
-            return resolve_method(method);
+            let result = resolve_method(method);
+            if !result.is_empty() {
+                return result;
+            }
+            // Fall through to the merged class — the method may lack a
+            // return type here but have one filled in from an interface
+            // via `@implements` generic resolution.
         }
 
-        // Walk up the inheritance chain
+        // Walk up the inheritance chain (also merges interface members
+        // with `@implements` generic substitutions applied).
         let merged = crate::virtual_members::resolve_class_fully_maybe_cached(
             class_info,
             class_loader,

src/completion/variable/foreach_resolution.rs

@@ -160,7 +160,9 @@ pub(in crate::completion) fn try_resolve_foreach_value_type<'b>(
             ctx.class_loader,
             ctx.resolved_class_cache,
         );
-        if let Some(value_type) = extract_iterable_element_type_from_class(&merged) {
+        if let Some(value_type) =
+            extract_iterable_element_type_from_class(&merged, ctx.class_loader)
+        {
             push_foreach_resolved_types(&value_type, ctx, results, conditional);
             return;
         }
@@ -261,7 +263,7 @@ pub(in crate::completion) fn try_resolve_foreach_key_type<'b>(
             ctx.class_loader,
             ctx.resolved_class_cache,
         );
-        if let Some(key_type) = extract_iterable_key_type_from_class(&merged) {
+        if let Some(key_type) = extract_iterable_key_type_from_class(&merged, ctx.class_loader) {
             push_foreach_resolved_types(&key_type, ctx, results, conditional);
             return;
         }
@@ -352,7 +354,10 @@ const ITERABLE_IFACE_NAMES: &[&str] = &[
 /// Returns `None` when no generic iterable annotation is found or
 /// when the element type is a scalar (scalars have no completable
 /// members).
-fn extract_iterable_element_type_from_class(class: &ClassInfo) -> Option<String> {
+fn extract_iterable_element_type_from_class(
+    class: &ClassInfo,
+    class_loader: &dyn Fn(&str) -> Option<ClassInfo>,
+) -> Option<String> {
     // 1. Check implements_generics for known iterable interfaces.
     for (name, args) in &class.implements_generics {
         let short = short_name(name);
@@ -364,6 +369,23 @@ fn extract_iterable_element_type_from_class(class: &ClassInfo) -> Option<String>
         }
     }
 
+    // 1b. Check implements_generics for interfaces that transitively
+    //     extend a known iterable interface (e.g. `TypedCollection`
+    //     extends `IteratorAggregate`).
+    for (name, args) in &class.implements_generics {
+        let short = short_name(name);
+        if !ITERABLE_IFACE_NAMES.contains(&short)
+            && !args.is_empty()
+            && let Some(iface) = class_loader(name)
+            && is_transitive_iterable(&iface, class_loader)
+        {
+            let value = args.last().unwrap();
+            if !docblock::types::is_scalar(value) {
+                return Some(value.clone());
+            }
+        }
+    }
+
     // 2. Check extends_generics — common for collection subclasses
     //    like `@extends Collection<int, User>`.
     for (_, args) in &class.extends_generics {
@@ -386,7 +408,10 @@ fn extract_iterable_element_type_from_class(class: &ClassInfo) -> Option<String>
 /// Returns `None` when no suitable annotation is found or when only a
 /// single type parameter is present (single-param generics have an
 /// implicit `int` key which is scalar).
-fn extract_iterable_key_type_from_class(class: &ClassInfo) -> Option<String> {
+fn extract_iterable_key_type_from_class(
+    class: &ClassInfo,
+    class_loader: &dyn Fn(&str) -> Option<ClassInfo>,
+) -> Option<String> {
     // 1. Check implements_generics for known iterable interfaces.
     for (name, args) in &class.implements_generics {
         let short = short_name(name);
@@ -398,6 +423,22 @@ fn extract_iterable_key_type_from_class(class: &ClassInfo) -> Option<String> {
         }
     }
 
+    // 1b. Check implements_generics for interfaces that transitively
+    //     extend a known iterable interface.
+    for (name, args) in &class.implements_generics {
+        let short = short_name(name);
+        if !ITERABLE_IFACE_NAMES.contains(&short)
+            && args.len() >= 2
+            && let Some(iface) = class_loader(name)
+            && is_transitive_iterable(&iface, class_loader)
+        {
+            let key = &args[0];
+            if !docblock::types::is_scalar(key) {
+                return Some(key.clone());
+            }
+        }
+    }
+
     // 2. Check extends_generics.
     for (_, args) in &class.extends_generics {
         if args.len() >= 2 {
@@ -411,6 +452,39 @@ fn extract_iterable_key_type_from_class(class: &ClassInfo) -> Option<String> {
     None
 }
 
+/// Check whether an interface transitively extends a known iterable
+/// interface (e.g. `TypedCollection extends IteratorAggregate`).
+fn is_transitive_iterable(
+    iface: &ClassInfo,
+    class_loader: &dyn Fn(&str) -> Option<ClassInfo>,
+) -> bool {
+    // Check direct interfaces.
+    for parent in &iface.interfaces {
+        let s = short_name(parent);
+        if ITERABLE_IFACE_NAMES.contains(&s) {
+            return true;
+        }
+    }
+    // Check extends_generics for the interface-extends-interface pattern.
+    for (name, _) in &iface.extends_generics {
+        let s = short_name(name);
+        if ITERABLE_IFACE_NAMES.contains(&s) {
+            return true;
+        }
+    }
+    // Check parent class (interfaces use `parent_class` for extends).
+    if let Some(ref parent_name) = iface.parent_class {
+        let s = short_name(parent_name);
+        if ITERABLE_IFACE_NAMES.contains(&s) {
+            return true;
+        }
+        if let Some(parent) = class_loader(parent_name) {
+            return is_transitive_iterable(&parent, class_loader);
+        }
+    }
+    false
+}
+
 // ─── Destructuring Resolution ───────────────────────────────────────
 
 /// Check whether the target variable appears inside an array/list

src/completion/variable/resolution.rs

@@ -369,6 +369,43 @@ fn resolve_variable_in_members<'b>(
                             break;
                         }
                     }
+
+                    // Neither native hint nor docblock resolved.
+                    // Check the fully-resolved class (with interface
+                    // members merged and `@implements` generics applied)
+                    // for a more specific parameter type.  This handles
+                    // cases where the class declares `map(object $entity)`
+                    // but the interface has `@param TEntity $entity` with
+                    // `@implements Interface<Boo>` substituting `TEntity`.
+                    let method_name = method.name.value.to_string();
+                    let merged = crate::virtual_members::resolve_class_fully_maybe_cached(
+                        ctx.current_class,
+                        ctx.class_loader,
+                        ctx.resolved_class_cache,
+                    );
+                    if let Some(merged_method) =
+                        merged.methods.iter().find(|m| m.name == method_name)
+                    {
+                        // Find the matching parameter by name.
+                        // ParameterInfo.name includes the `$` prefix.
+                        if let Some(merged_param) = merged_method
+                            .parameters
+                            .iter()
+                            .find(|p| p.name == ctx.var_name)
+                            && let Some(ref hint) = merged_param.type_hint
+                        {
+                            let resolved = crate::completion::type_resolution::type_hint_to_classes(
+                                hint,
+                                &ctx.current_class.name,
+                                ctx.all_classes,
+                                ctx.class_loader,
+                            );
+                            if !resolved.is_empty() {
+                                param_results = resolved;
+                                break;
+                            }
+                        }
+                    }
                 }
             }