Support @mixin union types and expose all member classes

Author: AJenbo

docs/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **`@mixin` with union types.** `@mixin Foo|Bar` now correctly exposes members from all classes in the union. Previously only single-class mixins were recognized.
 - **`throw new` completion no longer offers non-instantiable types.** Interfaces, abstract classes, traits, and enums are now filtered out, matching the behavior of `new` completion. The `throw new` path also now filters to Throwable descendants only.
 - **Unified class name completion architecture.** `throw new` and `catch()` completion now use the same `build_class_name_completions` pipeline as `new`, `extends`, `implements`, etc. `throw new` uses a `ThrowNew` context (instantiable + Throwable) and `catch()`/`@throws` uses a `Catch` context (class or interface + Throwable). This gives both contexts the same affinity scoring, FQN shortening via use-map, namespace segment drill-down, deprecation flags, and consistent filtering. The separate `build_catch_class_name_completions` function has been removed.
 - **Consolidated class completion passes.** The previous 5-pass architecture (use-map, same-namespace, fqn_uri_index, fqn_uri_index duplicate, stub_index) has been simplified to 2 passes (fqn_uri_index + stub_index) with an inline `classify` closure that determines tier (`'0'` use-imported, `'1'` same/sub-namespace, `'2'` everything else) per candidate. The redundant pass 4 (identical to pass 3) is eliminated, and tier assignment is now based on proximity checks rather than which data source produced the item.

src/docblock/tags.rs

@@ -248,26 +248,37 @@ pub fn extract_mixin_tags_from_info(info: &DocblockInfo) -> Vec<(String, Vec<Php
         // Parse the type token into a structured PhpType and extract
         // the base class name and optional generic arguments.
         let parsed = PhpType::parse(type_token);
-        let (base, generic_args) = match &parsed {
-            PhpType::Generic(name, args) => {
-                let cleaned_args: Vec<PhpType> = args.iter().map(strip_fqn_prefix_typed).collect();
-                (name.clone(), cleaned_args)
-            }
-            PhpType::Named(name) => (name.clone(), vec![]),
-            PhpType::Nullable(inner) => match inner.as_ref() {
-                PhpType::Named(name) => (name.clone(), vec![]),
+
+        // Collect individual type members. A union like `Foo|Bar` yields
+        // multiple mixin entries, one per member.
+        let members: Vec<&PhpType> = match &parsed {
+            PhpType::Union(parts) => parts.iter().collect(),
+            other => vec![other],
+        };
+
+        for member in members {
+            let (base, generic_args) = match member {
                 PhpType::Generic(name, args) => {
                     let cleaned_args: Vec<PhpType> =
                         args.iter().map(strip_fqn_prefix_typed).collect();
                     (name.clone(), cleaned_args)
                 }
+                PhpType::Named(name) => (name.clone(), vec![]),
+                PhpType::Nullable(inner) => match inner.as_ref() {
+                    PhpType::Named(name) => (name.clone(), vec![]),
+                    PhpType::Generic(name, args) => {
+                        let cleaned_args: Vec<PhpType> =
+                            args.iter().map(strip_fqn_prefix_typed).collect();
+                        (name.clone(), cleaned_args)
+                    }
+                    _ => continue,
+                },
                 _ => continue,
-            },
-            _ => continue,
-        };
+            };
 
-        if !base.is_empty() {
-            results.push((base, generic_args));
+            if !base.is_empty() {
+                results.push((base, generic_args));
+            }
         }
     }
 

tests/integration/completion_generics.rs

@@ -7702,6 +7702,79 @@ class KlaviyoClient {
     }
 }
 
+/// When `@mixin Foo|Bar` is used, members from both classes should be available.
+#[tokio::test]
+async fn test_mixin_union_type() {
+    let backend = create_test_backend();
+
+    let uri = Url::parse("file:///mixin_union.php").unwrap();
+    let text = concat!(
+        "<?php\n",
+        "class Webpage {\n",
+        "    public function getUrl(): string {}\n",
+        "}\n",
+        "class AwaitableWebpage {\n",
+        "    public function doAwait(): void {}\n",
+        "}\n",
+        "/**\n",
+        " * @mixin Webpage|AwaitableWebpage\n",
+        " */\n",
+        "final class PendingAwaitablePage {\n",
+        "    public function pending(): bool {}\n",
+        "}\n",
+        "$page = new PendingAwaitablePage();\n",
+        "$page->\n",
+    );
+    let open_params = DidOpenTextDocumentParams {
+        text_document: TextDocumentItem {
+            uri: uri.clone(),
+            language_id: "php".to_string(),
+            version: 1,
+            text: text.to_string(),
+        },
+    };
+    backend.did_open(open_params).await;
+
+    let line = text.lines().count() as u32 - 1;
+    let completion_params = CompletionParams {
+        text_document_position: TextDocumentPositionParams {
+            text_document: TextDocumentIdentifier { uri },
+            position: Position { line, character: 7 },
+        },
+        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 names: Vec<&str> = items
+                .iter()
+                .map(|i| i.filter_text.as_deref().unwrap_or(&i.label))
+                .collect();
+            assert!(
+                names.contains(&"getUrl"),
+                "Union mixin should include Webpage::getUrl(), got: {:?}",
+                names
+            );
+            assert!(
+                names.contains(&"doAwait"),
+                "Union mixin should include AwaitableWebpage::doAwait(), got: {:?}",
+                names
+            );
+            assert!(
+                names.contains(&"pending"),
+                "Own method pending() should be present, got: {:?}",
+                names
+            );
+        }
+        _ => panic!("Expected CompletionResponse::Array"),
+    }
+}
+
 /// When `@param Closure(T): void $cb` receives `fn(User $u) => ...`,
 /// the template param `T` should be inferred from the closure's parameter
 /// type (contravariant position).

tests/unit/docblock_parsing.rs

@@ -1306,6 +1306,39 @@ fn mixin_tag_empty_after_tag() {
     assert!(mixins.is_empty());
 }
 
+#[test]
+fn mixin_tag_union() {
+    let doc = concat!("/**\n", " * @mixin Webpage|AwaitableWebpage\n", " */",);
+    let mixins = extract_mixin_tags(doc);
+    assert_eq!(
+        mixins,
+        vec![
+            ("Webpage".to_string(), vec![]),
+            ("AwaitableWebpage".to_string(), vec![]),
+        ]
+    );
+}
+
+#[test]
+fn mixin_tag_union_with_generics() {
+    let doc = concat!(
+        "/**\n",
+        " * @mixin Builder<User>|Collection<int, User>\n",
+        " */",
+    );
+    let mixins = extract_mixin_tags(doc);
+    assert_eq!(
+        mixins,
+        vec![
+            ("Builder".to_string(), vec![PhpType::parse("User")]),
+            (
+                "Collection".to_string(),
+                vec![PhpType::parse("int"), PhpType::parse("User")],
+            ),
+        ]
+    );
+}
+
 // ─── @phpstan-assert / @psalm-assert extraction ─────────────────────────
 
 #[test]