Trait insteadof / as Conflict Resolution

Author: AJenbo

example.php

@@ -1127,6 +1127,35 @@ public function arrayMapFallback(): void
 }
 
 
+// ── Trait insteadof / as Conflict Resolution ────────────────────────────────
+
+/**
+ * Demonstrates trait conflict resolution with `insteadof` and `as`.
+ *
+ * When multiple traits define the same method, PHP requires explicit
+ * `insteadof` to pick a winner and `as` to create aliases.
+ */
+class TraitConflictDemo
+{
+    use JsonSerializer, XmlSerializer {
+        JsonSerializer::serialize insteadof XmlSerializer;
+        XmlSerializer::serialize as serializeXml;
+        JsonSerializer::serialize as private internalSerialize;
+    }
+
+    public function demo(): void
+    {
+        // Try: $this->  — offers serialize (from JsonSerializer), serializeXml (alias),
+        //                  internalSerialize (alias), toJson, toXml, and demo
+        $this->serialize();               // JsonSerializer wins via insteadof
+        $this->serializeXml();            // XmlSerializer::serialize aliased
+        $this->internalSerialize();       // JsonSerializer::serialize aliased as private
+        $this->toJson();                  // non-conflicting method from JsonSerializer
+        $this->toXml();                   // non-conflicting method from XmlSerializer
+    }
+}
+
+
 // ═══════════════════════════════════════════════════════════════════════════
 // ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
 // ┃  SCAFFOLDING — Supporting definitions below this line.              ┃
@@ -1153,6 +1182,16 @@ public function log(string $message): void;
 
 // ─── Traits ─────────────────────────────────────────────────────────────────
 
+trait JsonSerializer {
+    public function serialize(): string { return '{}'; }
+    public function toJson(): string { return $this->serialize(); }
+}
+
+trait XmlSerializer {
+    public function serialize(): string { return '<xml/>'; }
+    public function toXml(): string { return $this->serialize(); }
+}
+
 trait HasTimestamps
 {
     protected ?string $createdAt = null;

src/definition/member.rs

@@ -123,13 +123,47 @@ impl Backend {
         // 4. Try each candidate class and pick the first one where the
         //    member actually exists (directly or via inheritance).
         for target_class in &candidates {
+            // Check if the member name is a trait `as` alias on this class.
+            // If so, resolve to the original method name and (optionally) the
+            // source trait so we jump to the actual method definition rather
+            // than failing to find an alias that only exists after inheritance
+            // resolution.
+            let (effective_name, alias_trait) =
+                Self::resolve_trait_alias(target_class, member_name);
+
+            // If we know the exact source trait from the alias, go directly
+            // to that trait's method definition.
+            if let Some(ref trait_name) = alias_trait {
+                if let Some(trait_info) = class_loader(trait_name) {
+                    if Self::classify_member(&trait_info, &effective_name, access_hint).is_some() {
+                        if let Some((class_uri, class_content)) =
+                            self.find_class_file_content(&trait_info.name, uri, content)
+                            && let Some(member_position) = Self::find_member_position(
+                                &class_content,
+                                &effective_name,
+                                MemberKind::Method,
+                            )
+                            && let Ok(parsed_uri) = Url::parse(&class_uri)
+                        {
+                            return Some(Location {
+                                uri: parsed_uri,
+                                range: Range {
+                                    start: member_position,
+                                    end: member_position,
+                                },
+                            });
+                        }
+                    }
+                }
+            }
+
             let declaring_class =
-                Self::find_declaring_class(target_class, member_name, &class_loader)
+                Self::find_declaring_class(target_class, &effective_name, &class_loader)
                     .unwrap_or_else(|| target_class.clone());
 
             // Check that the member is actually present on the declaring class.
             let member_kind =
-                match Self::classify_member(&declaring_class, member_name, access_hint) {
+                match Self::classify_member(&declaring_class, &effective_name, access_hint) {
                     Some(k) => k,
                     None => continue, // member not on this candidate, try next
                 };
@@ -138,7 +172,7 @@ impl Backend {
             if let Some((class_uri, class_content)) =
                 self.find_class_file_content(&declaring_class.name, uri, content)
                 && let Some(member_position) =
-                    Self::find_member_position(&class_content, member_name, member_kind)
+                    Self::find_member_position(&class_content, &effective_name, member_kind)
                 && let Ok(parsed_uri) = Url::parse(&class_uri)
             {
                 return Some(Location {
@@ -155,15 +189,45 @@ impl Backend {
         // and try the original (non-iterating) logic so we at least get
         // partial results when possible.
         let target_class = &candidates[0];
-        let declaring_class = Self::find_declaring_class(target_class, member_name, &class_loader)
-            .unwrap_or_else(|| target_class.clone());
 
-        let member_kind = Self::classify_member(&declaring_class, member_name, access_hint)?;
+        let (effective_name, alias_trait) =
+            Self::resolve_trait_alias(target_class, member_name);
+
+        // Direct trait lookup for aliased members in the fallback path.
+        if let Some(ref trait_name) = alias_trait {
+            if let Some(trait_info) = class_loader(trait_name) {
+                if let Some((class_uri, class_content)) =
+                    self.find_class_file_content(&trait_info.name, uri, content)
+                    && let Some(member_position) = Self::find_member_position(
+                        &class_content,
+                        &effective_name,
+                        MemberKind::Method,
+                    )
+                    && let Ok(parsed_uri) = Url::parse(&class_uri)
+                {
+                    return Some(Location {
+                        uri: parsed_uri,
+                        range: Range {
+                            start: member_position,
+                            end: member_position,
+                        },
+                    });
+                }
+            }
+        }
+
+        let declaring_class =
+            Self::find_declaring_class(target_class, &effective_name, &class_loader)
+                .unwrap_or_else(|| target_class.clone());
+
+        let member_kind =
+            Self::classify_member(&declaring_class, &effective_name, access_hint)?;
 
         let (class_uri, class_content) =
             self.find_class_file_content(&declaring_class.name, uri, content)?;
 
-        let member_position = Self::find_member_position(&class_content, member_name, member_kind)?;
+        let member_position =
+            Self::find_member_position(&class_content, &effective_name, member_kind)?;
 
         let parsed_uri = Url::parse(&class_uri).ok()?;
         Some(Location {
@@ -380,6 +444,23 @@ impl Backend {
     ///
     /// Returns `Some(ClassInfo)` of the declaring class, or `None` if the
     /// member cannot be found in any ancestor.
+    /// Resolve a trait `as` alias on a class.
+    ///
+    /// If `member_name` matches a trait alias declared on the class, returns
+    /// the original method name and (optionally) the source trait name.
+    /// Otherwise returns `member_name` unchanged with no trait hint.
+    fn resolve_trait_alias(class: &ClassInfo, member_name: &str) -> (String, Option<String>) {
+        for alias in &class.trait_aliases {
+            if alias.alias.as_deref() == Some(member_name) {
+                return (
+                    alias.method_name.clone(),
+                    alias.trait_name.clone(),
+                );
+            }
+        }
+        (member_name.to_string(), None)
+    }
+
     fn find_declaring_class(
         class: &ClassInfo,
         member_name: &str,

src/inheritance.rs

@@ -15,7 +15,7 @@ use std::collections::HashMap;
 
 use crate::Backend;
 use crate::types::Visibility;
-use crate::types::{ClassInfo, MethodInfo, PropertyInfo};
+use crate::types::{ClassInfo, MethodInfo, PropertyInfo, TraitAlias, TraitPrecedence};
 
 impl Backend {
     /// Resolve a class together with all inherited members from its parent
@@ -48,6 +48,8 @@ impl Backend {
             &mut merged,
             &class.used_traits,
             &class.use_generics,
+            &class.trait_precedences,
+            &class.trait_aliases,
             class_loader,
             0,
         );
@@ -96,6 +98,8 @@ impl Backend {
                 &mut merged,
                 &parent.used_traits,
                 &parent.use_generics,
+                &parent.trait_precedences,
+                &parent.trait_aliases,
                 class_loader,
                 0,
             );
@@ -303,6 +307,8 @@ impl Backend {
         merged: &mut ClassInfo,
         trait_names: &[String],
         use_generics: &[(String, Vec<String>)],
+        trait_precedences: &[TraitPrecedence],
+        trait_aliases: &[TraitAlias],
         class_loader: &dyn Fn(&str) -> Option<ClassInfo>,
         depth: u32,
     ) {
@@ -331,6 +337,8 @@ impl Backend {
                     merged,
                     &trait_info.used_traits,
                     &trait_info.use_generics,
+                    &trait_info.trait_precedences,
+                    &trait_info.trait_aliases,
                     class_loader,
                     depth + 1,
                 );
@@ -360,6 +368,8 @@ impl Backend {
                         merged,
                         &parent.used_traits,
                         &parent.use_generics,
+                        &parent.trait_precedences,
+                        &parent.trait_aliases,
                         class_loader,
                         parent_depth + 1,
                     );
@@ -403,11 +413,46 @@ impl Backend {
 
             // Merge trait methods — skip if already present.
             // Apply generic substitution if a `@use` mapping exists.
+            // Also skip methods excluded by `insteadof` declarations.
             for method in &trait_info.methods {
+                // Check if this method from this trait is excluded by an
+                // `insteadof` declaration.  For example, if the class has
+                // `TraitA::method insteadof TraitB`, then when merging
+                // TraitB's methods, `method` should be skipped.
+                let excluded = trait_precedences.iter().any(|p| {
+                    p.method_name == method.name
+                        && p.insteadof.iter().any(|excluded_trait| {
+                            excluded_trait == trait_name
+                                || short_name(excluded_trait) == short_name(trait_name)
+                        })
+                });
+                if excluded {
+                    continue;
+                }
+
                 if merged.methods.iter().any(|m| m.name == method.name) {
                     continue;
                 }
                 let mut method = method.clone();
+
+                // Apply visibility-only `as` changes (no alias name).
+                // For example, `TraitA::method as protected` changes the
+                // visibility of `method` without creating an alias.
+                for alias in trait_aliases {
+                    if alias.method_name == method.name
+                        && alias.alias.is_none()
+                        && let Some(vis) = alias.visibility
+                    {
+                        // Check trait name matches (if specified)
+                        let name_matches = alias.trait_name.as_ref().is_none_or(|t| {
+                            t == trait_name || short_name(t) == short_name(trait_name)
+                        });
+                        if name_matches {
+                            method.visibility = vis;
+                        }
+                    }
+                }
+
                 if !trait_subs.is_empty() {
                     apply_substitution_to_method(&mut method, &trait_subs);
                 }
@@ -433,6 +478,51 @@ impl Backend {
                 }
                 merged.constants.push(constant.clone());
             }
+
+            // Apply `as` alias declarations that create new method names.
+            // For example, `TraitB::method as traitBMethod` creates a copy
+            // of `method` accessible as `traitBMethod`.
+            for alias in trait_aliases {
+                // Only process aliases that have a new name.
+                let alias_name = match &alias.alias {
+                    Some(name) => name,
+                    None => continue,
+                };
+
+                // Check trait name matches (if specified).
+                let name_matches = alias
+                    .trait_name
+                    .as_ref()
+                    .is_none_or(|t| t == trait_name || short_name(t) == short_name(trait_name));
+                if !name_matches {
+                    continue;
+                }
+
+                // Find the source method in this trait.
+                let source_method = trait_info
+                    .methods
+                    .iter()
+                    .find(|m| m.name == alias.method_name);
+                let source_method = match source_method {
+                    Some(m) => m,
+                    None => continue,
+                };
+
+                // Skip if an alias with this name already exists.
+                if merged.methods.iter().any(|m| m.name == *alias_name) {
+                    continue;
+                }
+
+                let mut aliased = source_method.clone();
+                aliased.name = alias_name.clone();
+                if let Some(vis) = alias.visibility {
+                    aliased.visibility = vis;
+                }
+                if !trait_subs.is_empty() {
+                    apply_substitution_to_method(&mut aliased, &trait_subs);
+                }
+                merged.methods.push(aliased);
+            }
         }
     }
 }

src/parser/ast_update.rs

@@ -238,6 +238,23 @@ impl Backend {
                 .map(|t| Self::resolve_name(t, use_map, namespace))
                 .collect();
 
+            // Resolve trait names in `insteadof` precedence adaptations
+            for prec in &mut class.trait_precedences {
+                prec.trait_name = Self::resolve_name(&prec.trait_name, use_map, namespace);
+                prec.insteadof = prec
+                    .insteadof
+                    .iter()
+                    .map(|t| Self::resolve_name(t, use_map, namespace))
+                    .collect();
+            }
+
+            // Resolve trait names in `as` alias adaptations
+            for alias in &mut class.trait_aliases {
+                if let Some(ref t) = alias.trait_name {
+                    alias.trait_name = Some(Self::resolve_name(t, use_map, namespace));
+                }
+            }
+
             // Resolve mixin names to fully-qualified names
             class.mixins = class
                 .mixins