Implement mixin method resolution and propagate @method/@Property tags

Author: AJenbo

docs/CHANGELOG.md

@@ -51,6 +51,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Stack overflow on large codebases and large files.** The `analyze` command and files with hundreds of class definitions no longer crash with stack overflows.
 - **`analyze` and `fix` commands run at consistent speed regardless of invocation style.** Running from within a project directory is no longer ~8x slower than using `--project-root`.
 - **Type narrowing.** Comprehensive fixes to type narrowing: non-exiting `if` branches no longer leak narrowed types into post-merge scope; `is_float()`, `is_null()`, and other `is_*()` guards correctly narrow multi-member unions; negated `instanceof` on nullable unions preserves `null`; `is_object()` narrows to all class types in a union (not just the first); `instanceof` on `mixed` or `object` narrows to the checked type; `=== null` and `== null` narrow to `null` in the truthy branch; `assert($x instanceof Foo)` followed by any `if` block no longer loses the narrowed type; falsy guard clauses strip both `false` and `null`; template-constrained types are expanded before guard filtering. `is_numeric()`, `is_bool()`, and `is_scalar()` guard clauses now narrow union types correctly. `exit` and `die` are recognized as unconditional exits for guard clause narrowing. Property access expressions (`$a->foo`) are now narrowed through chained if/elseif/else conditions using `is_string()`, `instanceof`, and other type guards. Array shape keys are now narrowed through null-check guard clauses and conditional reassignment (e.g. `$a["test"]` resolves to `int` instead of `?int` after `if ($a["test"] === null) { return; }`). After `instanceof` check plus reassignment inside the if-body, the post-merge type collapses to the common parent class instead of producing a redundant `Child|Parent` union. Property access after OR'd `instanceof` checks (`$a instanceof B || $a instanceof C`) now resolves to the union of all branches' property types.
+- **Mixin resolution.** Static method calls on instances of a class with `@mixin` now resolve through the mixin. `@method` and `@property` tags declared on a mixin class are propagated to the consuming class. `$this` return types on mixin methods resolve to the consumer class. `IteratorIterator` is now patched with `@template` parameters and `@mixin TIterator` (matching PHPStan's stubs).
 - **Generics.** Constructor generic inference now works through inherited constructors: child classes without their own constructor infer template parameters from the parent's constructor arguments, with correct remapping through multi-level `@extends` chains (including swapped or renamed template parameters). Function-level `@template` parameters bound to generic wrapper types (e.g. `@param Container<TItem> $c`) are inferred from arguments that extend the wrapper class. Method calls are now case-insensitive, matching PHP semantics (e.g. `$obj->getId()` finds `getID()`). Closure literals passed to `@template` parameters are recognised as `Closure`. Class-level template parameters are preserved through chained method calls. Template parameters fall back to their declared bound (or `mixed` when unbounded) when subclasses omit `@extends` or `@use` annotations. Unbound template parameters at call sites resolve to their declared bounds or `mixed` instead of leaking raw names. Method-level templates resolve correctly through generic wrappers and nested call chains. Return type generic arguments are preserved for template substitution, fixing false "expects TRelatedModel, got Translation" diagnostics. Iterating over a subclass that extends a generic collection with scalar type arguments (e.g. `IntCollection extends Collection<int, int>`) now yields the concrete scalar type instead of the raw template parameter name. Calling a method on a union of generic types (e.g. `$var->get()` where `$var` is `C<A>|C<B>`) now resolves to the union of each branch's return type (`A|B`) instead of only the first branch. Empty array literals passed to generic constructors or functions infer `never` for element type parameters (e.g. `new ArrayCollection([])` resolves to `ArrayCollection<never, never>`).
 - **Vendor functions and constants.** Functions and constants defined in vendor packages are now indexed at startup, eliminating false-positive "Function not found" diagnostics.
 - **Use-imported classes no longer shadowed by global-namespace stubs.** The use-map is now checked first for unqualified names, fixing Laravel Facade static method resolution.

docs/todo/bugs.md

@@ -178,21 +178,6 @@ Several return type patterns are not resolved:
 (lines 43, 64, 83, 121, 132, 146).
 
 
-## B20. Mixin method resolution gaps
-
-**Discovered:** SKIP audit of
-`tests/psalm_assertions/mixin_annotation.php`.
-
-`@mixin` method resolution fails in these cases:
-
-- Static method called on a class that mixes in another class
-- Method on `IteratorIterator` via mixin
-- Mixin method return type not resolved through `static`
-
-**Tests:** SKIPs in `tests/psalm_assertions/mixin_annotation.php`
-(lines 34, 73, 168).
-
-
 ## B21. Remaining static-late-binding and generics gaps
 
 **Discovered:** SKIP audit of

src/completion/variable/rhs_resolution.rs

@@ -2874,15 +2874,9 @@ fn resolve_rhs_static_call(
                 // parameters typed as `@param class-string<Foo> $var`
                 // where there is no `$var = Foo::class` assignment.
                 let resolved = resolve_var_types(&var_name, ctx, ctx.cursor_offset);
-                resolved.iter().find_map(|rt| match &rt.type_string {
-                    PhpType::ClassString(Some(inner)) => inner.base_name().map(|s| s.to_string()),
-                    PhpType::Nullable(inner) => match inner.as_ref() {
-                        PhpType::ClassString(Some(cs_inner)) => {
-                            cs_inner.base_name().map(|s| s.to_string())
-                        }
-                        _ => None,
-                    },
-                    PhpType::Union(members) => members.iter().find_map(|m| match m {
+                resolved
+                    .iter()
+                    .find_map(|rt| match &rt.type_string {
                         PhpType::ClassString(Some(inner)) => {
                             inner.base_name().map(|s| s.to_string())
                         }
@@ -2892,10 +2886,28 @@ fn resolve_rhs_static_call(
                             }
                             _ => None,
                         },
+                        PhpType::Union(members) => members.iter().find_map(|m| match m {
+                            PhpType::ClassString(Some(inner)) => {
+                                inner.base_name().map(|s| s.to_string())
+                            }
+                            PhpType::Nullable(inner) => match inner.as_ref() {
+                                PhpType::ClassString(Some(cs_inner)) => {
+                                    cs_inner.base_name().map(|s| s.to_string())
+                                }
+                                _ => None,
+                            },
+                            _ => None,
+                        }),
                         _ => None,
-                    }),
-                    _ => None,
-                })
+                    })
+                    .or_else(|| {
+                        // Final fallback: `$var::method()` where `$var` is an
+                        // object instance (not a class-string). In PHP you can
+                        // call static methods on an instance reference.
+                        resolved
+                            .iter()
+                            .find_map(|rt| rt.type_string.base_name().map(|s| s.to_string()))
+                    })
             }
         }
         _ => None,

src/stub_patches.rs

@@ -94,6 +94,14 @@
 //!    `@implements ArrayAccess<TKey, TValue>`.
 //!    PHPStan ref: `stubs/WeakMap.stub`
 //!
+//! 10. **`IteratorIterator`** — phpstorm-stubs lack `@template` and `@mixin`.
+//!     PHPStan adds `@template TKey`, `@template TValue`,
+//!     `@template TIterator of Traversable<TKey, TValue>`,
+//!     `@implements OuterIterator<TKey, TValue>`,
+//!     `@mixin TIterator`.  The `@mixin` makes methods from the wrapped
+//!     iterator available on the wrapper.
+//!     PHPStan ref: `stubs/iterable.stub`
+//!
 //! ## Removing patches
 //!
 //! When phpstorm-stubs gains proper annotations for a patched symbol,
@@ -188,6 +196,7 @@ pub fn apply_class_stub_patches(class: &mut ClassInfo) {
         "SplFixedArray" => patch_spl_fixed_array(class),
         "SplObjectStorage" => patch_spl_object_storage(class),
         "WeakMap" => patch_weak_map(class),
+        "IteratorIterator" => patch_iterator_iterator(class),
         _ => {}
     }
 }
@@ -317,6 +326,62 @@ fn patch_weak_map(class: &mut ClassInfo) {
     add_implements_generics(class, "ArrayAccess", &["TKey", "TValue"]);
 }
 
+/// Add `@template TKey`, `@template TValue`,
+/// `@template TIterator of Traversable<TKey, TValue>`,
+/// `@implements OuterIterator<TKey, TValue>`,
+/// `@mixin TIterator`.
+///
+/// PHPStan ref: `stubs/iterable.stub`
+fn patch_iterator_iterator(class: &mut ClassInfo) {
+    if !class.template_params.is_empty() {
+        return;
+    }
+    add_templates(class, &[("TKey", None), ("TValue", None)]);
+    // TIterator has a complex bound `Traversable<TKey, TValue>` — add it
+    // manually since `add_templates` only handles simple string bounds.
+    let t_iter = atom("TIterator");
+    if !class.template_params.contains(&t_iter) {
+        class.template_params.push(t_iter);
+    }
+    class
+        .template_param_bounds
+        .entry(atom("TIterator"))
+        .or_insert_with(|| {
+            PhpType::Generic(
+                "Traversable".to_string(),
+                vec![
+                    PhpType::Named("TKey".to_string()),
+                    PhpType::Named("TValue".to_string()),
+                ],
+            )
+        });
+    add_implements_generics(class, "OuterIterator", &["TKey", "TValue"]);
+    // Add @mixin TIterator so that methods from the wrapped iterator
+    // are available on the wrapper.
+    if !class.mixins.contains(&t_iter) {
+        class.mixins.push(t_iter);
+    }
+    // Patch the constructor: add template binding TIterator → $iterator
+    // so that `new IteratorIterator(new Subject())` infers TIterator = Subject.
+    if let Some(ctor_idx) = class
+        .methods
+        .iter()
+        .position(|m| m.name.as_str() == "__construct")
+    {
+        let mut ctor = (*class.methods[ctor_idx]).clone();
+        let binding = (atom("TIterator"), atom("$iterator"));
+        if !ctor.template_bindings.iter().any(|(t, _)| t == &binding.0) {
+            ctor.template_bindings.push(binding);
+        }
+        // Update the parameter type hint from Traversable to TIterator
+        // so that classify_template_binding recognises a Direct binding.
+        if let Some(param) = ctor.parameters.iter_mut().find(|p| p.name == "$iterator") {
+            param.type_hint = Some(PhpType::Named("TIterator".to_string()));
+        }
+        class.methods.make_mut()[ctor_idx] = std::sync::Arc::new(ctor);
+    }
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Helpers
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -651,4 +716,27 @@ mod tests {
         assert_eq!(class.template_params, original_params);
         assert!(class.implements_generics.is_empty());
     }
+
+    #[test]
+    fn iterator_iterator_gets_templates_and_mixin() {
+        let mut class = empty_class("IteratorIterator");
+        apply_class_stub_patches(&mut class);
+
+        assert_eq!(
+            class.template_params,
+            vec![atom("TKey"), atom("TValue"), atom("TIterator")]
+        );
+        assert!(
+            class
+                .implements_generics
+                .iter()
+                .any(|(n, args)| n.as_str() == "OuterIterator" && args.len() == 2),
+            "Should have @implements OuterIterator<TKey, TValue>"
+        );
+        assert_eq!(class.mixins, vec![atom("TIterator")]);
+        assert!(
+            class.template_param_bounds.contains_key(&atom("TIterator")),
+            "TIterator should have a bound"
+        );
+    }
 }

src/virtual_members/phpdoc.rs

@@ -698,6 +698,50 @@ fn collect_mixin_members(
             collector.constants.push(constant.clone());
         }
 
+        // ── Phase: @method/@property tags from the mixin's own docblock ──
+        // `resolve_class_with_inheritance` does NOT include virtual members
+        // from @method/@property tags (to avoid circular provider calls).
+        // Extract them manually so that e.g. `@mixin A` where A declares
+        // `@method $this active()` propagates `active()` to the consumer.
+        if let Some(doc_text) = mixin_class.class_docblock.as_deref()
+            && !doc_text.is_empty()
+        {
+            for mut m in docblock::extract_method_tags(doc_text) {
+                if !collector.dedup.methods.insert(m.name.to_string()) {
+                    continue;
+                }
+                if !subs.is_empty() {
+                    inheritance::apply_substitution_to_method(&mut m, &subs);
+                }
+                m.is_virtual = true;
+                collector.methods.push(m);
+            }
+
+            for (name, type_hint) in docblock::extract_property_tags(doc_text) {
+                if !collector.dedup.properties.insert(name.clone()) {
+                    continue;
+                }
+                let resolved_type = if !subs.is_empty() {
+                    type_hint.map(|t| t.substitute(&subs))
+                } else {
+                    type_hint
+                };
+                collector.properties.push(PropertyInfo {
+                    name: atom(&name),
+                    name_offset: 0,
+                    type_hint: resolved_type,
+                    native_type_hint: None,
+                    description: None,
+                    is_static: false,
+                    visibility: Visibility::Public,
+                    deprecation_message: None,
+                    deprecated_replacement: None,
+                    see_refs: Vec::new(),
+                    is_virtual: true,
+                });
+            }
+        }
+
         // Recurse into mixins declared by the mixin class itself.
         if !mixin_class.mixins.is_empty() {
             collect_mixin_members(

tests/integration/hover.rs

@@ -10580,3 +10580,108 @@ if ($a instanceof PropA || $a instanceof PropB) {
         text
     );
 }
+
+#[test]
+fn hover_static_mixin_method_on_instance() {
+    let backend = create_test_backend();
+    let uri = "file:///test.php";
+    let content = r#"<?php
+class MixProvider {
+    public static function getInt(): int {
+        return 5;
+    }
+}
+
+/** @mixin MixProvider */
+class MixChild {
+    public function __call(string $name, array $args) {}
+    public static function __callStatic(string $name, array $args) {}
+}
+
+$child = new MixChild();
+$b = $child::getInt();
+"#;
+
+    // Hover on `$b` (line 14, char 0)
+    let hover = hover_at(&backend, uri, content, 14, 1).expect("expected hover");
+    let text = hover_text(&hover);
+    assert!(
+        text.contains("int"),
+        "should resolve static mixin method return type: {}",
+        text
+    );
+}
+
+#[test]
+fn hover_mixin_this_return_type() {
+    let backend = create_test_backend();
+    let uri = "file:///test.php";
+    let content = r#"<?php
+/**
+ * @method $this active()
+ */
+class MixinBase {
+    public function __call(string $name, array $arguments) {}
+}
+
+/**
+ * @mixin MixinBase
+ */
+class MixConsumer {
+    public function __call(string $name, array $arguments) {}
+}
+
+$b = new MixConsumer;
+$c = $b->active();
+"#;
+
+    // Hover on `$c` (line 16, char 1)
+    let hover = hover_at(&backend, uri, content, 16, 1).expect("expected hover");
+    let text = hover_text(&hover);
+    assert!(
+        text.contains("MixConsumer"),
+        "$this on mixin method should resolve to the consumer class: {}",
+        text
+    );
+}
+
+#[test]
+fn hover_iterator_iterator_mixin_method() {
+    let backend = create_test_backend();
+    let uri = "file:///test.php";
+    let content = r#"<?php
+class Subject implements Iterator {
+    public function index(int $idx): bool {
+        return true;
+    }
+    public function current(): int { return 2; }
+    public function next(): void {}
+    public function key(): int { return 1; }
+    public function valid(): bool { return false; }
+    public function rewind(): void {}
+}
+
+/**
+ * @template TKey
+ * @template TValue
+ * @template TIterator of Traversable
+ * @mixin TIterator
+ */
+class IteratorIterator {
+    /** @param TIterator $iterator */
+    public function __construct(Traversable $iterator) {}
+}
+
+$iter = new IteratorIterator(new Subject());
+$b = $iter->index(0);
+"#;
+
+    // Hover on `$b` (line 24, char 1)
+    let hover = hover_at(&backend, uri, content, 24, 1).expect("expected hover");
+    let text = hover_text(&hover);
+    assert!(
+        text.contains("bool"),
+        "should resolve mixin method return type from wrapped iterator: {}",
+        text
+    );
+}

tests/psalm_assertions/mixin_annotation.php

@@ -31,7 +31,7 @@ class Child extends ParentClass {}
     $b = $child::getInt();
 
     assertType('string', $a);
-    assertType('int', $b); // SKIP — static mixin method return type not resolved
+    assertType('int', $b);
 }
 
 // Test: wrapCustomIterator
@@ -70,7 +70,7 @@ public function rewind() {}
     $iter = new IteratorIterator(new Subject());
     $b = $iter->index(0);
 
-    assertType('bool', $b); // SKIP — mixin method on IteratorIterator not resolved
+    assertType('bool', $b); // SKIP — IteratorIterator not in fixture runner stubs (feature works with full stubs)
 }
 
 // Test: templatedMixin
@@ -165,6 +165,6 @@ public function __call(string $name, array $arguments) {}
     $b = new B;
     $c = $b->active();
 
-    assertType('B', $c); // SKIP — mixin method return type not resolved through static
+    assertType('B', $c);
 }