Add support for traits

Author: AJenbo

src/completion/resolver.rs

@@ -132,16 +132,17 @@ impl Backend {
         // method calls (`$this->getService()`),
         // and static method calls (`ClassName::make()`).
         if subject.ends_with(')')
-            && let Some((call_body, args_text)) = split_call_subject(subject) {
-                return Self::resolve_call_return_types(
-                    call_body,
-                    args_text,
-                    current_class,
-                    all_classes,
-                    class_loader,
-                    function_loader,
-                );
-            }
+            && let Some((call_body, args_text)) = split_call_subject(subject)
+        {
+            return Self::resolve_call_return_types(
+                call_body,
+                args_text,
+                current_class,
+                all_classes,
+                class_loader,
+                function_loader,
+            );
+        }
 
         // ── Property-chain: $this->prop  or  $this?->prop ──
         if let Some(prop_name) = subject
@@ -1101,6 +1102,13 @@ impl Backend {
     ) -> ClassInfo {
         let mut merged = class.clone();
 
+        // 1. Merge traits used by this class.
+        //    PHP precedence: class methods > trait methods > inherited methods.
+        //    Since `merged` already contains the class's own members, we only
+        //    add trait members that don't collide with existing ones.
+        Self::merge_traits_into(&mut merged, &class.used_traits, class_loader, 0);
+
+        // 2. Walk up the `extends` chain and merge parent members.
         let mut current = class.clone();
         let mut depth = 0;
         const MAX_DEPTH: u32 = 20;
@@ -1117,6 +1125,10 @@ impl Backend {
                 break;
             };
 
+            // Merge traits used by the parent class as well, so that
+            // grandparent-level trait members are visible.
+            Self::merge_traits_into(&mut merged, &parent.used_traits, class_loader, 0);
+
             // Merge parent methods — skip private, skip if child already has one with same name
             for method in &parent.methods {
                 if method.visibility == Visibility::Private {
@@ -1155,6 +1167,67 @@ impl Backend {
 
         merged
     }
+
+    /// Recursively merge members from the given traits into `merged`.
+    ///
+    /// Traits can themselves `use` other traits (composition), so this
+    /// method recurses up to `MAX_TRAIT_DEPTH` levels.  Members that
+    /// already exist in `merged` (by name) are skipped — this naturally
+    /// implements the PHP precedence rule where the current class's own
+    /// members win over trait members, and earlier-listed traits win
+    /// over later ones.
+    ///
+    /// Private trait members *are* merged (unlike parent class private
+    /// members), because PHP copies trait members into the using class
+    /// regardless of visibility.
+    fn merge_traits_into(
+        merged: &mut ClassInfo,
+        trait_names: &[String],
+        class_loader: &dyn Fn(&str) -> Option<ClassInfo>,
+        depth: u32,
+    ) {
+        const MAX_TRAIT_DEPTH: u32 = 20;
+        if depth > MAX_TRAIT_DEPTH {
+            return;
+        }
+
+        for trait_name in trait_names {
+            let trait_info = if let Some(t) = class_loader(trait_name) {
+                t
+            } else {
+                continue;
+            };
+
+            // Recursively merge traits used by this trait (trait composition).
+            if !trait_info.used_traits.is_empty() {
+                Self::merge_traits_into(merged, &trait_info.used_traits, class_loader, depth + 1);
+            }
+
+            // Merge trait methods — skip if already present
+            for method in &trait_info.methods {
+                if merged.methods.iter().any(|m| m.name == method.name) {
+                    continue;
+                }
+                merged.methods.push(method.clone());
+            }
+
+            // Merge trait properties
+            for property in &trait_info.properties {
+                if merged.properties.iter().any(|p| p.name == property.name) {
+                    continue;
+                }
+                merged.properties.push(property.clone());
+            }
+
+            // Merge trait constants
+            for constant in &trait_info.constants {
+                if merged.constants.iter().any(|c| c.name == constant.name) {
+                    continue;
+                }
+                merged.constants.push(constant.clone());
+            }
+        }
+    }
 }
 
 // ─── PHPStan Conditional Return Type Resolution ─────────────────────────────

src/definition/resolve.rs

@@ -683,6 +683,13 @@ impl Backend {
             return Some(class.clone());
         }
 
+        // Check traits used by this class.
+        if let Some(found) =
+            Self::find_declaring_in_traits(&class.used_traits, member_name, class_loader, 0)
+        {
+            return Some(found);
+        }
+
         // Walk up the parent chain.
         let mut current = class.clone();
         for _ in 0..MAX_DEPTH {
@@ -691,12 +698,56 @@ impl Backend {
             if Self::classify_member(&parent, member_name).is_some() {
                 return Some(parent);
             }
+            // Check traits used by the parent class.
+            if let Some(found) =
+                Self::find_declaring_in_traits(&parent.used_traits, member_name, class_loader, 0)
+            {
+                return Some(found);
+            }
             current = parent;
         }
 
         None
     }
 
+    /// Search through a list of trait names for one that declares `member_name`.
+    ///
+    /// Traits can themselves `use` other traits, so this recurses up to a
+    /// depth limit to handle trait composition.
+    fn find_declaring_in_traits(
+        trait_names: &[String],
+        member_name: &str,
+        class_loader: &dyn Fn(&str) -> Option<ClassInfo>,
+        depth: usize,
+    ) -> Option<ClassInfo> {
+        const MAX_TRAIT_DEPTH: usize = 20;
+        if depth > MAX_TRAIT_DEPTH {
+            return None;
+        }
+
+        for trait_name in trait_names {
+            let trait_info = if let Some(t) = class_loader(trait_name) {
+                t
+            } else {
+                continue;
+            };
+            if Self::classify_member(&trait_info, member_name).is_some() {
+                return Some(trait_info);
+            }
+            // Recurse into traits used by this trait.
+            if let Some(found) = Self::find_declaring_in_traits(
+                &trait_info.used_traits,
+                member_name,
+                class_loader,
+                depth + 1,
+            ) {
+                return Some(found);
+            }
+        }
+
+        None
+    }
+
     // ─── File & Position Lookup ─────────────────────────────────────────────
 
     /// Find the file URI and content for the file that contains a given class.

src/parser.rs

@@ -517,7 +517,7 @@ impl Backend {
                         .as_ref()
                         .and_then(|ext| ext.types.first().map(|ident| ident.value().to_string()));
 
-                    let (methods, properties, constants) =
+                    let (methods, properties, constants, used_traits) =
                         Self::extract_class_like_members(class.members.iter(), doc_ctx);
 
                     let start_offset = class.left_brace.start.offset;
@@ -531,6 +531,7 @@ impl Backend {
                         start_offset,
                         end_offset,
                         parent_class,
+                        used_traits,
                     });
                 }
                 Statement::Interface(iface) => {
@@ -543,7 +544,7 @@ impl Backend {
                         .as_ref()
                         .and_then(|ext| ext.types.first().map(|ident| ident.value().to_string()));
 
-                    let (methods, properties, constants) =
+                    let (methods, properties, constants, used_traits) =
                         Self::extract_class_like_members(iface.members.iter(), doc_ctx);
 
                     let start_offset = iface.left_brace.start.offset;
@@ -557,6 +558,27 @@ impl Backend {
                         start_offset,
                         end_offset,
                         parent_class,
+                        used_traits,
+                    });
+                }
+                Statement::Trait(trait_def) => {
+                    let trait_name = trait_def.name.value.to_string();
+
+                    let (methods, properties, constants, used_traits) =
+                        Self::extract_class_like_members(trait_def.members.iter(), doc_ctx);
+
+                    let start_offset = trait_def.left_brace.start.offset;
+                    let end_offset = trait_def.right_brace.end.offset;
+
+                    classes.push(ClassInfo {
+                        name: trait_name,
+                        methods,
+                        properties,
+                        constants,
+                        start_offset,
+                        end_offset,
+                        parent_class: None,
+                        used_traits,
                     });
                 }
                 Statement::Namespace(namespace) => {
@@ -571,20 +593,28 @@ impl Backend {
         }
     }
 
-    /// Extract methods, properties, and constants from class-like members.
+    /// Extract methods, properties, constants, and used trait names from
+    /// class-like members.
     ///
-    /// This is shared between `Statement::Class` and `Statement::Interface`
-    /// since both use the same `ClassLikeMember` representation.
+    /// This is shared between `Statement::Class`, `Statement::Interface`,
+    /// and `Statement::Trait` since all use the same `ClassLikeMember`
+    /// representation.
     ///
     /// When `doc_ctx` is provided, PHPDoc `@return` and `@var` tags are used
     /// to refine (or supply) type information for methods and properties.
     fn extract_class_like_members<'a>(
         members: impl Iterator<Item = &'a ClassLikeMember<'a>>,
         doc_ctx: Option<&DocblockCtx<'a>>,
-    ) -> (Vec<MethodInfo>, Vec<PropertyInfo>, Vec<ConstantInfo>) {
+    ) -> (
+        Vec<MethodInfo>,
+        Vec<PropertyInfo>,
+        Vec<ConstantInfo>,
+        Vec<String>,
+    ) {
         let mut methods = Vec::new();
         let mut properties = Vec::new();
         let mut constants = Vec::new();
+        let mut used_traits = Vec::new();
 
         for member in members {
             match member {
@@ -675,11 +705,16 @@ impl Backend {
                         });
                     }
                 }
+                ClassLikeMember::TraitUse(trait_use) => {
+                    for trait_name_ident in trait_use.trait_names.iter() {
+                        used_traits.push(trait_name_ident.value().to_string());
+                    }
+                }
                 _ => {}
             }
         }
 
-        (methods, properties, constants)
+        (methods, properties, constants, used_traits)
     }
 
     /// Update the ast_map, use_map, and namespace_map for a given file URI
@@ -718,7 +753,7 @@ impl Backend {
                             Statement::Use(use_stmt) => {
                                 Self::extract_use_items(&use_stmt.items, &mut use_map);
                             }
-                            Statement::Class(_) | Statement::Interface(_) => {
+                            Statement::Class(_) | Statement::Interface(_) | Statement::Trait(_) => {
                                 Self::extract_classes_from_statements(
                                     std::iter::once(inner),
                                     &mut classes,
@@ -741,7 +776,7 @@ impl Backend {
                         }
                     }
                 }
-                Statement::Class(_) | Statement::Interface(_) => {
+                Statement::Class(_) | Statement::Interface(_) | Statement::Trait(_) => {
                     Self::extract_classes_from_statements(
                         std::iter::once(statement),
                         &mut classes,
@@ -834,6 +869,12 @@ impl Backend {
                 let resolved = Self::resolve_name(parent, use_map, namespace);
                 class.parent_class = Some(resolved);
             }
+            // Resolve trait names to fully-qualified names
+            class.used_traits = class
+                .used_traits
+                .iter()
+                .map(|t| Self::resolve_name(t, use_map, namespace))
+                .collect();
         }
     }
 

src/types.rs

@@ -192,4 +192,7 @@ pub struct ClassInfo {
     /// The parent class name from the `extends` clause, if any.
     /// This is the raw name as written in source (e.g. "BaseClass", "Foo\\Bar").
     pub parent_class: Option<String>,
+    /// Trait names used by this class via `use TraitName;` statements.
+    /// These are resolved to fully-qualified names during post-processing.
+    pub used_traits: Vec<String>,
 }