Resolve @mixin template parameters via property generic types

Author: AJenbo

docs/CHANGELOG.md

@@ -89,7 +89,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Single generic argument on collections bound to the wrong template parameter.** Writing `Collection<SectionTranslation>` on a class with `@template TKey of array-key` and `@template TValue` assigned the argument to `TKey` (by position), leaving `TValue` unsubstituted. When fewer generic arguments are provided than template parameters and the leading parameters have key-like bounds (`array-key`, `int`, `string`), the arguments are now right-aligned so they bind to the value parameters. Method-level template parameters whose bound parameter was not passed at the call site and defaults to `null` now resolve to `null` instead of remaining as raw template names. Together these fixes mean `Collection<SectionTranslation>::first()` correctly resolves to `SectionTranslation|null`.
 - **Nullable return types losing `|null` after template substitution.** When a method declared `@return TValue|null` and `TValue` was substituted with a concrete class through `@extends`, the `|null` component was silently dropped. Hover showed `AdminUser` instead of `AdminUser|null` for calls like `AdminUser::first()`. The docblock type extraction pipeline now preserves nullable unions so that `|null` survives through substitution, hover display, and variable type resolution.
 - **Loop-body assignments not visible inside the same loop iteration.** When a variable was initialized as `null` and reassigned later in a loop body, code earlier in the loop (reached on subsequent iterations) only saw `null`. The variable resolution walker now pre-scans the entire loop body for assignments before the positional walk, so the union of all assignments is available at every point inside the loop. Combined with `!== null` narrowing, variables like `$lastPaidEnd` correctly resolve to the assigned class type. Applies to `foreach`, `while`, `for`, and `do-while` loops.
-- **`@mixin` referencing a template parameter now resolves.** When a class declares `@template T` and `@mixin T`, the mixin name is substituted with the concrete type from the generic arguments. For example, a wrapper class `Subclient<EventsApi>` with `@mixin TWraps` now pulls in `EventsApi`'s methods instead of silently ignoring the mixin because no class named `TWraps` exists.
+- **`@mixin` referencing a template parameter now resolves.** When a class declares `@template T` and `@mixin T`, the mixin name is substituted with the concrete type from the generic arguments. For example, a wrapper class `Subclient<EventsApi>` with `@mixin TWraps` now pulls in `EventsApi`'s methods instead of silently ignoring the mixin because no class named `TWraps` exists. The initial fix only handled the ancestor-walk path (`ChildClass extends Wrapper<Concrete>`); the direct-property-access path (`/** @var Wrapper<Concrete> */ public $prop`) now also works. Additionally, mixin names that are template parameters are no longer FQN-resolved during parsing (which turned `TWraps` into `Namespace\TWraps`, breaking the template-param match).
 - **Eloquent `where{Property}()` methods from docblock-only `@property` tags.** Models that declare columns only via `@property` annotations (without `$casts`, `$fillable`, etc.) now correctly get `where{PropertyName}()` methods on `Builder<Model>`.
 
 ## [0.6.0] - 2026-03-26

src/completion/types/resolution.rs

@@ -19,7 +19,7 @@
 ///   type alias reference.
 use std::sync::Arc;
 
-use crate::inheritance::apply_generic_args;
+use crate::inheritance::{apply_generic_args, build_generic_subs};
 use crate::php_type::PhpType;
 use crate::types::*;
 use crate::util::{find_class_by_name, short_name};
@@ -362,6 +362,26 @@ fn resolve_named_type(
                 };
                 let mut result = apply_generic_args(&resolved, &generic_args);
 
+                // ── Template-param mixin resolution ────────────────
+                // When a class declares `@mixin TParam` where `TParam`
+                // is a template parameter, the mixin cannot be resolved
+                // during `resolve_class_fully` because the concrete type
+                // is not yet known.  Now that generic args are concrete,
+                // resolve those mixins and merge their members.
+                if cls.mixins.iter().any(|m| cls.template_params.contains(m)) {
+                    let subs = build_generic_subs(&cls, &generic_args);
+                    if !subs.is_empty() {
+                        let mixin_members = virtual_members::phpdoc::resolve_template_param_mixins(
+                            &cls,
+                            &subs,
+                            class_loader,
+                        );
+                        if !mixin_members.is_empty() {
+                            virtual_members::merge_virtual_members(&mut result, mixin_members);
+                        }
+                    }
+                }
+
                 // ── Eloquent Builder scope injection ───────────────
                 laravel::try_inject_builder_scopes(
                     &mut result,

src/completion/variable/rhs_resolution.rs

@@ -469,8 +469,29 @@ fn resolve_rhs_instantiation(
                             type_arg_strings.iter().map(|s| s.as_str()).collect();
                         let resolved =
                             crate::virtual_members::resolve_class_fully(cls, ctx.class_loader);
-                        let substituted =
+                        let mut substituted =
                             crate::inheritance::apply_generic_args(&resolved, &type_args);
+
+                        // ── Template-param mixin resolution ────────────────
+                        // When a class declares `@mixin TParam` where `TParam`
+                        // is a template parameter, the mixin cannot be resolved
+                        // during `resolve_class_fully` because the concrete type
+                        // is not yet known.  Now that generic args are concrete,
+                        // resolve those mixins and merge their members.
+                        if cls.mixins.iter().any(|m| cls.template_params.contains(m)) {
+                            let generic_subs = crate::inheritance::build_generic_subs(cls, &type_args);
+                            if !generic_subs.is_empty() {
+                                let mixin_members = crate::virtual_members::phpdoc::resolve_template_param_mixins(
+                                    cls,
+                                    &generic_subs,
+                                    ctx.class_loader,
+                                );
+                                if !mixin_members.is_empty() {
+                                    crate::virtual_members::merge_virtual_members(&mut substituted, mixin_members);
+                                }
+                            }
+                        }
+
                         return vec![ResolvedType::from_class(substituted)];
                     }
                 }

src/inheritance.rs

@@ -999,25 +999,17 @@ pub(crate) fn apply_substitution<'a>(
     }
 }
 
-/// Apply explicit generic type arguments to a class's members.
-///
-/// When a type hint includes generic parameters (e.g. `Collection<int, User>`),
-/// this function maps them to the class's `@template` parameters and rewrites
-/// all method return types, method parameter types, and property type hints
-/// with the concrete types.
+/// Build a substitution map from a class's template parameters and
+/// concrete type arguments.
 ///
-/// If the class has no `template_params` or no `type_args` are provided,
-/// returns a clone of the class unchanged.
-///
-/// # Example
+/// Handles right-alignment when fewer arguments than template parameters
+/// are provided (see [`apply_generic_args`] for details on the heuristic).
 ///
-/// Given a `Collection` class with `@template TKey` and `@template TValue`,
-/// calling `apply_generic_args(&collection_class, &["int", "User"])` will
-/// substitute every occurrence of `TKey` with `int` and `TValue` with `User`
-/// in the class's methods and properties.
-pub(crate) fn apply_generic_args(class: &ClassInfo, type_args: &[&str]) -> ClassInfo {
+/// Returns an empty map when no substitutions can be made (e.g. when
+/// `template_params` or `type_args` is empty).
+pub(crate) fn build_generic_subs(class: &ClassInfo, type_args: &[&str]) -> HashMap<String, PhpType> {
     if class.template_params.is_empty() || type_args.is_empty() {
-        return class.clone();
+        return HashMap::new();
     }
 
     // When fewer type arguments are provided than template parameters,
@@ -1053,6 +1045,28 @@ pub(crate) fn apply_generic_args(class: &ClassInfo, type_args: &[&str]) -> Class
         }
     }
 
+    subs
+}
+
+/// Apply explicit generic type arguments to a class's members.
+///
+/// When a type hint includes generic parameters (e.g. `Collection<int, User>`),
+/// this function maps them to the class's `@template` parameters and rewrites
+/// all method return types, method parameter types, and property type hints
+/// with the concrete types.
+///
+/// If the class has no `template_params` or no `type_args` are provided,
+/// returns a clone of the class unchanged.
+///
+/// # Example
+///
+/// Given a `Collection` class with `@template TKey` and `@template TValue`,
+/// calling `apply_generic_args(&collection_class, &["int", "User"])` will
+/// substitute every occurrence of `TKey` with `int` and `TValue` with `User`
+/// in the class's methods and properties.
+pub(crate) fn apply_generic_args(class: &ClassInfo, type_args: &[&str]) -> ClassInfo {
+    let subs = build_generic_subs(class, type_args);
+
     if subs.is_empty() {
         return class.clone();
     }

src/parser/ast_update.rs

@@ -633,11 +633,21 @@ impl Backend {
                 }
             }
 
-            // Resolve mixin names to fully-qualified names
+            // Resolve mixin names to fully-qualified names.
+            // Skip names that match a template parameter — these are
+            // not class names but placeholders that will be substituted
+            // with concrete types when the generic class is instantiated
+            // (e.g. `@template TWraps` + `@mixin TWraps`).
             class.mixins = class
                 .mixins
                 .iter()
-                .map(|m| Self::resolve_name(m, use_map, namespace))
+                .map(|m| {
+                    if class.template_params.contains(m) {
+                        m.clone()
+                    } else {
+                        Self::resolve_name(m, use_map, namespace)
+                    }
+                })
                 .collect();
 
             // Resolve custom collection class name to FQN

src/virtual_members/phpdoc.rs

@@ -605,6 +605,83 @@ fn collect_mixin_members(
     }
 }
 
+/// Resolve `@mixin` tags that name a template parameter, using concrete
+/// generic arguments provided at a call site.
+///
+/// During [`PHPDocProvider::provide`], mixin names that are template
+/// parameters (e.g. `@mixin TWraps`) cannot be resolved because the
+/// concrete type arguments are not yet known — they are applied later
+/// by [`apply_generic_args`](crate::inheritance::apply_generic_args).
+/// This function fills that gap: after generic substitution has been
+/// performed, call it with the **original** (unsubstituted) class and
+/// the substitution map to collect members from the now-concrete mixin
+/// classes.
+///
+/// Only mixins whose names match a template parameter are processed;
+/// non-template mixins were already resolved during `provide`.
+///
+/// The returned [`VirtualMembers`](super::VirtualMembers) should be
+/// merged into the substituted class via
+/// [`merge_virtual_members`](super::merge_virtual_members).
+pub fn resolve_template_param_mixins(
+    original_class: &ClassInfo,
+    template_subs: &HashMap<String, PhpType>,
+    class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
+) -> super::VirtualMembers {
+    if template_subs.is_empty() || original_class.mixins.is_empty() {
+        return super::VirtualMembers {
+            methods: Vec::new(),
+            properties: Vec::new(),
+            constants: Vec::new(),
+        };
+    }
+
+    // Only process mixins whose name is a template parameter — the
+    // rest were already resolved during `PHPDocProvider::provide`.
+    let template_mixins: Vec<String> = original_class
+        .mixins
+        .iter()
+        .filter(|m| original_class.template_params.contains(m))
+        .cloned()
+        .collect();
+
+    if template_mixins.is_empty() {
+        return super::VirtualMembers {
+            methods: Vec::new(),
+            properties: Vec::new(),
+            constants: Vec::new(),
+        };
+    }
+
+    let dedup = MixinDedup {
+        methods: HashSet::new(),
+        properties: HashSet::new(),
+        constants: HashSet::new(),
+    };
+
+    let mut collector = MixinCollector {
+        methods: Vec::new(),
+        properties: Vec::new(),
+        constants: Vec::new(),
+        dedup,
+    };
+
+    collect_mixin_members(
+        &template_mixins,
+        &original_class.mixin_generics,
+        class_loader,
+        &mut collector,
+        template_subs,
+        0,
+    );
+
+    super::VirtualMembers {
+        methods: collector.methods,
+        properties: collector.properties,
+        constants: collector.constants,
+    }
+}
+
 /// Build a substitution map for mixin generic resolution by zipping the
 /// parent class's `@template` parameters with the type arguments provided
 /// by the child's `@extends` / `@implements` generics.

tests/integration/completion_generics.rs

@@ -7389,3 +7389,118 @@ async fn test_function_template_param_resolves_to_bound_inside_body() {
         _ => panic!("Expected CompletionResponse::Array"),
     }
 }
+
+/// When a class declares `@template TWraps` and `@mixin TWraps`, and a
+/// property is typed as `Wrapper<ConcreteApi>`, the mixin should resolve
+/// `TWraps` → `ConcreteApi` and expose `ConcreteApi`'s methods on the
+/// property.  This is the "direct property access" scenario — no child
+/// class extends the wrapper; the concrete type comes entirely from the
+/// `@var` generic annotation on the property.
+///
+/// Reproduces the Klaviyo SDK pattern:
+///   `/** @var Subclient<EventsApi> */ public $Events;`
+#[tokio::test]
+async fn test_mixin_template_param_resolved_via_property_generic_type() {
+    let backend = create_test_backend();
+
+    let wrapper_uri = Url::parse("file:///Subclient.php").unwrap();
+    let wrapper_text = r#"<?php
+/**
+ * @template TWraps of object
+ * @mixin TWraps
+ */
+class Subclient {
+    public function getApiInstance(): object {}
+}
+"#;
+
+    let api_uri = Url::parse("file:///EventsApi.php").unwrap();
+    let api_text = r#"<?php
+class EventsApi {
+    public function createEvent(array $body): array {}
+    public function getEvents(string $filter): array {}
+    public function deleteEvent(string $id): void {}
+}
+"#;
+
+    let consumer_uri = Url::parse("file:///KlaviyoClient.php").unwrap();
+    let consumer_text = r#"<?php
+class KlaviyoClient {
+    /** @var Subclient<EventsApi> */
+    public $Events;
+
+    function test() {
+        $this->Events->
+    }
+}
+"#;
+
+    // Open all files
+    for (uri, text) in [
+        (&wrapper_uri, wrapper_text),
+        (&api_uri, api_text),
+        (&consumer_uri, consumer_text),
+    ] {
+        backend
+            .did_open(DidOpenTextDocumentParams {
+                text_document: TextDocumentItem {
+                    uri: uri.clone(),
+                    language_id: "php".to_string(),
+                    version: 1,
+                    text: text.to_string(),
+                },
+            })
+            .await;
+    }
+
+    let completion_params = CompletionParams {
+        text_document_position: TextDocumentPositionParams {
+            text_document: TextDocumentIdentifier {
+                uri: consumer_uri.clone(),
+            },
+            position: Position {
+                line: 6,
+                character: 24,
+            },
+        },
+        work_done_progress_params: WorkDoneProgressParams::default(),
+        partial_result_params: PartialResultParams::default(),
+        context: None,
+    };
+
+    let result = backend.completion(completion_params).await.unwrap();
+    assert!(result.is_some(), "Completion should return results");
+
+    match result.unwrap() {
+        CompletionResponse::Array(items) => {
+            let method_names: Vec<&str> = items
+                .iter()
+                .filter(|i| i.kind == Some(CompletionItemKind::METHOD))
+                .map(|i| i.filter_text.as_deref().unwrap_or(&i.label))
+                .collect();
+
+            assert!(
+                method_names.contains(&"createEvent"),
+                "Mixin template param via @var Subclient<EventsApi> should expose 'createEvent', got: {:?}",
+                method_names
+            );
+            assert!(
+                method_names.contains(&"getEvents"),
+                "Mixin template param via @var Subclient<EventsApi> should expose 'getEvents', got: {:?}",
+                method_names
+            );
+            assert!(
+                method_names.contains(&"deleteEvent"),
+                "Mixin template param via @var Subclient<EventsApi> should expose 'deleteEvent', got: {:?}",
+                method_names
+            );
+            // The wrapper's own method should also be present.
+            assert!(
+                method_names.contains(&"getApiInstance"),
+                "Wrapper's own method 'getApiInstance' should still be present, got: {:?}",
+                method_names
+            );
+        }
+        _ => panic!("Expected CompletionResponse::Array"),
+    }
+}