Detect cross-trait method collisions when a class uses multiple traits

When a class uses multiple traits that define the same method without
`insteadof` resolution, PHP reports a fatal error. Add detection for
this case in DuplicateDeclarationRule via a new checkTraitMethodCollisions
helper method.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: phpstan-bot

src/Rules/Classes/DuplicateDeclarationHelper.php

@@ -6,9 +6,13 @@
 use PhpParser\Node\Stmt\ClassConst;
 use PhpParser\Node\Stmt\ClassLike;
 use PhpParser\Node\Stmt\EnumCase;
+use PhpParser\Node\Stmt\TraitUse;
+use PhpParser\Node\Stmt\TraitUseAdaptation\Precedence;
+use PHPStan\Reflection\ClassReflection;
 use PHPStan\Rules\RuleErrorBuilder;
 use PHPStan\ShouldNotHappenException;
 use function array_key_exists;
+use function count;
 use function is_string;
 use function sprintf;
 use function strtolower;
@@ -119,4 +123,85 @@ public static function checkClassLike(ClassLike $classLike, string $displayName,
 		return $errors;
 	}
 
+	/**
+	 * @return list<\PHPStan\Rules\IdentifierRuleError>
+	 */
+	public static function checkTraitMethodCollisions(ClassLike $classLike, ClassReflection $classReflection): array
+	{
+		$errors = [];
+
+		// Collect insteadof adaptations: trait::method pairs that are excluded
+		$excludedTraitMethods = [];
+		foreach ($classLike->stmts as $stmt) {
+			if (!$stmt instanceof TraitUse) {
+				continue;
+			}
+			foreach ($stmt->adaptations as $adaptation) {
+				if (!$adaptation instanceof Precedence) {
+					continue;
+				}
+				$methodName = strtolower($adaptation->method->name);
+				foreach ($adaptation->insteadof as $excludedTrait) {
+					$excludedTraitMethods[strtolower($excludedTrait->toString()) . '::' . $methodName] = true;
+				}
+			}
+		}
+
+		// Collect class-defined methods (these override trait methods)
+		$classDefinedMethods = [];
+		foreach ($classLike->getMethods() as $method) {
+			$classDefinedMethods[strtolower($method->name->name)] = true;
+		}
+
+		// Collect methods from each trait
+		/** @var array<string, list<array{string, string}>> $methodTraits methodNameLower => [[traitDisplayName, originalMethodName], ...] */
+		$methodTraits = [];
+		$traits = $classReflection->getTraits();
+		foreach ($traits as $trait) {
+			foreach ($trait->getNativeReflection()->getMethods() as $method) {
+				$methodNameLower = strtolower($method->getName());
+
+				// Skip if this method is excluded via insteadof
+				$key = strtolower($trait->getName()) . '::' . $methodNameLower;
+				if (array_key_exists($key, $excludedTraitMethods)) {
+					continue;
+				}
+
+				// Skip if the class defines this method (class overrides traits)
+				if (array_key_exists($methodNameLower, $classDefinedMethods)) {
+					continue;
+				}
+
+				$methodTraits[$methodNameLower][] = [$trait->getDisplayName(), $method->getName()];
+			}
+		}
+
+		// Find the use statement line for error reporting
+		$useLine = null;
+		foreach ($classLike->stmts as $stmt) {
+			if ($stmt instanceof TraitUse) {
+				$useLine = $stmt->getStartLine();
+				break;
+			}
+		}
+
+		// Report conflicts
+		foreach ($methodTraits as $traitInfos) {
+			if (count($traitInfos) <= 1) {
+				continue;
+			}
+
+			$errors[] = RuleErrorBuilder::message(sprintf(
+				'Trait method %s has not been applied, because there are collisions with other trait methods on %s.',
+				$traitInfos[1][0] . '::' . $traitInfos[1][1] . '()',
+				$classReflection->getDisplayName(),
+			))->identifier('class.traitMethodCollision')
+				->line($useLine ?? $classLike->getStartLine())
+				->nonIgnorable()
+				->build();
+		}
+
+		return $errors;
+	}
+
 }

src/Rules/Classes/DuplicateDeclarationRule.php

@@ -7,6 +7,7 @@
 use PHPStan\DependencyInjection\RegisteredRule;
 use PHPStan\Node\InClassNode;
 use PHPStan\Rules\Rule;
+use function array_merge;
 use function strtolower;
 
 /**
@@ -25,10 +26,16 @@ public function processNode(Node $node, Scope $scope): array
 	{
 		$classReflection = $node->getClassReflection();
 
-		return DuplicateDeclarationHelper::checkClassLike(
-			$node->getOriginalNode(),
-			$classReflection->getDisplayName(),
-			strtolower($classReflection->getClassTypeDescription()),
+		return array_merge(
+			DuplicateDeclarationHelper::checkClassLike(
+				$node->getOriginalNode(),
+				$classReflection->getDisplayName(),
+				strtolower($classReflection->getClassTypeDescription()),
+			),
+			DuplicateDeclarationHelper::checkTraitMethodCollisions(
+				$node->getOriginalNode(),
+				$classReflection,
+			),
 		);
 	}
 

tests/PHPStan/Rules/Classes/DuplicateDeclarationRuleTest.php

@@ -66,6 +66,30 @@ public function testDuplicatePromotedProperty(): void
 		]);
 	}
 
+	public function testBug14250TraitMethodCollisions(): void
+	{
+		$this->analyse([__DIR__ . '/data/bug-14250.php'], [
+			[
+				'Trait method Bug14250\MyTrait2::doSomething() has not been applied, because there are collisions with other trait methods on Bug14250\FooWithMultipleConflictingTraits.',
+				93,
+			],
+		]);
+	}
+
+	public function testTraitMethodCollisions(): void
+	{
+		$this->analyse([__DIR__ . '/data/trait-method-collisions.php'], [
+			[
+				'Trait method TraitMethodCollisions\TraitB::doSomething() has not been applied, because there are collisions with other trait methods on TraitMethodCollisions\UnresolvedCollision.',
+				22,
+			],
+			[
+				'Trait method TraitMethodCollisions\TraitD::foo() has not been applied, because there are collisions with other trait methods on TraitMethodCollisions\PartialCollision.',
+				76,
+			],
+		]);
+	}
+
 	#[RequiresPhp('>= 8.1')]
 	public function testDuplicateEnumCase(): void
 	{

tests/PHPStan/Rules/Classes/data/trait-method-collisions.php

@@ -0,0 +1,77 @@
+<?php declare(strict_types = 1);
+
+namespace TraitMethodCollisions;
+
+trait TraitA
+{
+	public function doSomething(): void
+	{
+	}
+}
+
+trait TraitB
+{
+	public function doSomething(): void
+	{
+	}
+}
+
+// Should report collision - two traits with same method, no insteadof
+class UnresolvedCollision
+{
+	use TraitA, TraitB;
+}
+
+// Should not report - collision resolved via insteadof
+class ResolvedCollision
+{
+	use TraitA, TraitB {
+		TraitA::doSomething insteadof TraitB;
+	}
+}
+
+// Should not report - class defines the method itself
+class ClassOverridesTraitMethod
+{
+	use TraitA, TraitB {
+		TraitA::doSomething insteadof TraitB;
+	}
+
+	public function doSomething(): void
+	{
+	}
+}
+
+// Should not report - single trait, no collision possible
+class SingleTrait
+{
+	use TraitA;
+}
+
+trait TraitC
+{
+	public function foo(): void
+	{
+	}
+
+	public function bar(): void
+	{
+	}
+}
+
+trait TraitD
+{
+	public function foo(): void
+	{
+	}
+
+	public function baz(): void
+	{
+	}
+}
+
+// Should report collision for foo only
+class PartialCollision
+{
+	use TraitC, TraitD;
+}