Support enum cases

janedbal · janedbal · commit 2526e5cb2949 · 2025-04-14T10:38:12.000+02:00
diff --git a/src/Reflection/ClassReflection.php b/src/Reflection/ClassReflection.php
@@ -162,7 +162,7 @@ public function __construct(
 		private PhpDocInheritanceResolver $phpDocInheritanceResolver,
 		private PhpVersion $phpVersion,
 		private SignatureMapProvider $signatureMapProvider,
-		private DeprecationProvider $deprecationResolver,
+		private DeprecationProvider $deprecationProvider,
 		private AttributeReflectionFactory $attributeReflectionFactory,
 		private array $propertiesClassReflectionExtensions,
 		private array $methodsClassReflectionExtensions,
@@ -795,7 +795,8 @@ public function getEnumCases(): array
 				$valueType = $this->initializerExprTypeResolver->getType($case->getValueExpression(), $initializerExprContext);
 			}
 			$caseName = $case->getName();
-			$cases[$caseName] = new EnumCaseReflection($this, $case, $valueType, $this->attributeReflectionFactory->fromNativeReflection($case->getAttributes(), InitializerExprContext::fromClass($this->getName(), $this->getFileName())));
+			$attributes = $this->attributeReflectionFactory->fromNativeReflection($case->getAttributes(), InitializerExprContext::fromClass($this->getName(), $this->getFileName()));
+			$cases[$caseName] = new EnumCaseReflection($this, $case, $valueType, $attributes, $this->deprecationProvider);
 		}
 
 		return $this->enumCases = $cases;
@@ -821,7 +822,9 @@ public function getEnumCase(string $name): EnumCaseReflection
 			$valueType = $this->initializerExprTypeResolver->getType($case->getValueExpression(), InitializerExprContext::fromClassReflection($this));
 		}
 
-		return new EnumCaseReflection($this, $case, $valueType, $this->attributeReflectionFactory->fromNativeReflection($case->getAttributes(), InitializerExprContext::fromClass($this->getName(), $this->getFileName())));
+		$attributes = $this->attributeReflectionFactory->fromNativeReflection($case->getAttributes(), InitializerExprContext::fromClass($this->getName(), $this->getFileName()));
+
+		return new EnumCaseReflection($this, $case, $valueType, $attributes, $this->deprecationProvider);
 	}
 
 	public function isClass(): bool
@@ -1081,7 +1084,7 @@ public function getConstant(string $name): ClassConstantReflection
 				throw new MissingConstantFromReflectionException($this->getName(), $name);
 			}
 
-			$deprecation = $this->deprecationResolver->getClassConstantDeprecation($reflectionConstant);
+			$deprecation = $this->deprecationProvider->getClassConstantDeprecation($reflectionConstant);
 			$deprecatedDescription = $deprecation === null ? null : $deprecation->getDescription();
 			$isDeprecated = $deprecation !== null;
 
@@ -1239,7 +1242,7 @@ public function isDeprecated(): bool
 	 */
 	private function resolveDeprecation(): void
 	{
-		$deprecation = $this->deprecationResolver->isClassDeprecated($this->reflection);
+		$deprecation = $this->deprecationProvider->isClassDeprecated($this->reflection);
 		if ($deprecation !== null) {
 			$this->isDeprecated = true;
 			$this->deprecatedDescription = $deprecation->getDescription();
@@ -1587,7 +1590,7 @@ public function withTypes(array $types): self
 			$this->phpDocInheritanceResolver,
 			$this->phpVersion,
 			$this->signatureMapProvider,
-			$this->deprecationResolver,
+			$this->deprecationProvider,
 			$this->attributeReflectionFactory,
 			$this->propertiesClassReflectionExtensions,
 			$this->methodsClassReflectionExtensions,
@@ -1619,7 +1622,7 @@ public function withVariances(array $variances): self
 			$this->phpDocInheritanceResolver,
 			$this->phpVersion,
 			$this->signatureMapProvider,
-			$this->deprecationResolver,
+			$this->deprecationProvider,
 			$this->attributeReflectionFactory,
 			$this->propertiesClassReflectionExtensions,
 			$this->methodsClassReflectionExtensions,
@@ -1661,7 +1664,7 @@ public function asFinal(): self
 			$this->phpDocInheritanceResolver,
 			$this->phpVersion,
 			$this->signatureMapProvider,
-			$this->deprecationResolver,
+			$this->deprecationProvider,
 			$this->attributeReflectionFactory,
 			$this->propertiesClassReflectionExtensions,
 			$this->methodsClassReflectionExtensions,
diff --git a/src/Reflection/Deprecation/DeprecationProvider.php b/src/Reflection/Deprecation/DeprecationProvider.php
@@ -5,6 +5,8 @@
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionClass;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionClassConstant;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionEnum;
+use PHPStan\BetterReflection\Reflection\Adapter\ReflectionEnumBackedCase;
+use PHPStan\BetterReflection\Reflection\Adapter\ReflectionEnumUnitCase;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionFunction;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionMethod;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionProperty;
@@ -32,6 +34,9 @@ final class DeprecationProvider
 	/** @var array<ConstantDeprecationExtension> $constantDeprecationExtensions */
 	private array $constantDeprecationExtensions;
 
+	/** @var array<EnumCaseDeprecationExtension> $enumCaseDeprecationExtensions */
+	private array $enumCaseDeprecationExtensions;
+
 	public function __construct(
 		Container $container,
 	)
@@ -42,6 +47,7 @@ public function __construct(
 		$this->classDeprecationExtensions = $container->getServicesByTag('phpstan.classDeprecationExtension');
 		$this->functionDeprecationExtensions = $container->getServicesByTag('phpstan.functionDeprecationExtension');
 		$this->constantDeprecationExtensions = $container->getServicesByTag('phpstan.constantDeprecationExtension');
+		$this->enumCaseDeprecationExtensions = $container->getServicesByTag('phpstan.enumCaseDeprecationExtension');
 	}
 
 	public function getPropertyDeprecation(ReflectionProperty $reflectionProperty): ?Deprecation
@@ -116,4 +122,16 @@ public function getConstantDeprecation(ReflectionConstant $constantReflection):
 		return null;
 	}
 
+	public function getEnumCaseDeprecation(ReflectionEnumUnitCase|ReflectionEnumBackedCase $enumCaseReflection): ?Deprecation
+	{
+		foreach ($this->enumCaseDeprecationExtensions as $extension) {
+			$deprecation = $extension->getEnumCaseDeprecation($enumCaseReflection);
+			if ($deprecation !== null) {
+				return $deprecation;
+			}
+		}
+
+		return null;
+	}
+
 }
diff --git a/src/Reflection/Deprecation/EnumCaseDeprecationExtension.php b/src/Reflection/Deprecation/EnumCaseDeprecationExtension.php
@@ -0,0 +1,28 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Reflection\Deprecation;
+
+use PHPStan\BetterReflection\Reflection\Adapter\ReflectionEnumBackedCase;
+use PHPStan\BetterReflection\Reflection\Adapter\ReflectionEnumUnitCase;
+
+/**
+ * This interface allows you to provide custom deprecation information
+ *
+ * To register it in the configuration file use the following tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyProvider
+ *		tags:
+ *			- phpstan.enumCaseDeprecationExtension
+ * ```
+ *
+ * @api
+ */
+interface EnumCaseDeprecationExtension
+{
+
+	public function getEnumCaseDeprecation(ReflectionEnumUnitCase|ReflectionEnumBackedCase $reflection): ?Deprecation;
+
+}
diff --git a/src/Reflection/EnumCaseReflection.php b/src/Reflection/EnumCaseReflection.php
@@ -5,6 +5,7 @@
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionEnumBackedCase;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionEnumUnitCase;
 use PHPStan\Internal\DeprecatedAttributeHelper;
+use PHPStan\Reflection\Deprecation\DeprecationProvider;
 use PHPStan\TrinaryLogic;
 use PHPStan\Type\Type;
 
@@ -14,6 +15,10 @@
 final class EnumCaseReflection
 {
 
+	private bool $isDeprecated;
+
+	private ?string $deprecatedDescription;
+
 	/**
 	 * @param list<AttributeReflection> $attributes
 	 */
@@ -22,8 +27,22 @@ public function __construct(
 		private ReflectionEnumUnitCase|ReflectionEnumBackedCase $reflection,
 		private ?Type $backingValueType,
 		private array $attributes,
+		DeprecationProvider $deprecationProvider,
 	)
 	{
+		$deprecation = $deprecationProvider->getEnumCaseDeprecation($reflection);
+		if ($deprecation !== null) {
+			$this->isDeprecated = true;
+			$this->deprecatedDescription = $deprecation->getDescription();
+
+		} elseif ($reflection->isDeprecated()) {
+			$attributes = $this->reflection->getBetterReflection()->getAttributes();
+			$this->isDeprecated = true;
+			$this->deprecatedDescription = DeprecatedAttributeHelper::getDeprecatedDescription($attributes);
+		} else {
+			$this->isDeprecated = false;
+			$this->deprecatedDescription = null;
+		}
 	}
 
 	public function getDeclaringEnum(): ClassReflection
@@ -43,17 +62,12 @@ public function getBackingValueType(): ?Type
 
 	public function isDeprecated(): TrinaryLogic
 	{
-		return TrinaryLogic::createFromBoolean($this->reflection->isDeprecated());
+		return TrinaryLogic::createFromBoolean($this->isDeprecated);
 	}
 
 	public function getDeprecatedDescription(): ?string
 	{
-		if ($this->reflection->isDeprecated()) {
-			$attributes = $this->reflection->getBetterReflection()->getAttributes();
-			return DeprecatedAttributeHelper::getDeprecatedDescription($attributes);
-		}
-
-		return null;
+		return $this->deprecatedDescription;
 	}
 
 	/**
diff --git a/tests/PHPStan/Reflection/Deprecation/DeprecationProviderTest.php b/tests/PHPStan/Reflection/Deprecation/DeprecationProviderTest.php
@@ -7,6 +7,7 @@
 use CustomDeprecations\DoubleDeprecatedClass;
 use CustomDeprecations\DoubleDeprecatedClassOnlyAttributeMessage;
 use CustomDeprecations\DoubleDeprecatedClassOnlyPhpDocMessage;
+use CustomDeprecations\MyDeprecatedEnum;
 use CustomDeprecations\NotDeprecatedClass;
 use CustomDeprecations\PhpDocDeprecatedClass;
 use CustomDeprecations\PhpDocDeprecatedClassWithMessage;
@@ -58,6 +59,24 @@ public function testCustomDeprecations(): void
 		$scopeForDoubleDeprecatedClassOnlyNativeMessage = $scopeFactory->create(ScopeContext::create('dummy.php')->enterClass($doubleDeprecatedClassOnlyPhpDocMessage));
 		$scopeForDoubleDeprecatedClassOnlyCustomMessage = $scopeFactory->create(ScopeContext::create('dummy.php')->enterClass($doubleDeprecatedClassOnlyAttributeMessage));
 
+		// enum cases
+		$myEnum = $reflectionProvider->getClass(MyDeprecatedEnum::class);
+
+		self::assertTrue($myEnum->isDeprecated());
+		self::assertNull($myEnum->getDeprecatedDescription());
+
+		self::assertTrue($myEnum->getEnumCase('CustomDeprecated')->isDeprecated()->yes());
+		self::assertSame('custom', $myEnum->getEnumCase('CustomDeprecated')->getDeprecatedDescription());
+
+		self::assertTrue($myEnum->getEnumCase('NativeDeprecated')->isDeprecated()->yes());
+		self::assertSame('native', $myEnum->getEnumCase('NativeDeprecated')->getDeprecatedDescription());
+
+		self::assertTrue($myEnum->getEnumCase('PhpDocDeprecated')->isDeprecated()->yes());
+		self::assertNull($myEnum->getEnumCase('PhpDocDeprecated')->getDeprecatedDescription()); // this should not be null
+
+		self::assertFalse($myEnum->getEnumCase('NotDeprecated')->isDeprecated()->yes());
+		self::assertNull($myEnum->getEnumCase('NotDeprecated')->getDeprecatedDescription());
+
 		// class
 		self::assertFalse($notDeprecatedClass->isDeprecated());
 		self::assertNull($notDeprecatedClass->getDeprecatedDescription());
diff --git a/tests/PHPStan/Reflection/Deprecation/data/CustomDeprecationExtension.php b/tests/PHPStan/Reflection/Deprecation/data/CustomDeprecationExtension.php
@@ -8,6 +8,8 @@
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionClass;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionClassConstant;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionEnum;
+use PHPStan\BetterReflection\Reflection\Adapter\ReflectionEnumBackedCase;
+use PHPStan\BetterReflection\Reflection\Adapter\ReflectionEnumUnitCase;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionFunction;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionMethod;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionProperty;
@@ -16,6 +18,7 @@
 use PHPStan\Reflection\Deprecation\ClassDeprecationExtension;
 use PHPStan\Reflection\Deprecation\ConstantDeprecationExtension;
 use PHPStan\Reflection\Deprecation\Deprecation;
+use PHPStan\Reflection\Deprecation\EnumCaseDeprecationExtension;
 use PHPStan\Reflection\Deprecation\FunctionDeprecationExtension;
 use PHPStan\Reflection\Deprecation\MethodDeprecationExtension;
 use PHPStan\Reflection\Deprecation\PropertyDeprecationExtension;
@@ -26,7 +29,8 @@ class CustomDeprecationExtension implements
 	ClassConstantDeprecationExtension,
 	MethodDeprecationExtension,
 	PropertyDeprecationExtension,
-	FunctionDeprecationExtension
+	FunctionDeprecationExtension,
+	EnumCaseDeprecationExtension
 {
 
 	public function getClassDeprecation(ReflectionClass|ReflectionEnum $reflection): ?Deprecation
@@ -59,6 +63,11 @@ public function getClassConstantDeprecation(ReflectionClassConstant $reflection)
 		return $this->buildDeprecation($reflection);
 	}
 
+	public function getEnumCaseDeprecation(ReflectionEnumBackedCase|ReflectionEnumUnitCase $reflection): ?Deprecation
+	{
+		return $this->buildDeprecation($reflection);
+	}
+
 	private function buildDeprecation($reflection): ?Deprecation
 	{
 		foreach ($reflection->getAttributes(CustomDeprecated::class) as $attribute) {
@@ -70,5 +79,4 @@ private function buildDeprecation($reflection): ?Deprecation
 
 		return null;
 	}
-
 }
diff --git a/tests/PHPStan/Reflection/Deprecation/data/deprecation-provider.neon b/tests/PHPStan/Reflection/Deprecation/data/deprecation-provider.neon
@@ -8,3 +8,4 @@ services:
 			- phpstan.classDeprecationExtension
 			- phpstan.functionDeprecationExtension
 			- phpstan.constantDeprecationExtension
+			- phpstan.enumCaseDeprecationExtension
diff --git a/tests/PHPStan/Reflection/Deprecation/data/deprecations.php b/tests/PHPStan/Reflection/Deprecation/data/deprecations.php
@@ -161,3 +161,22 @@ function doubleDeprecatedFunctionOnlyAttributeMessage() {}
 /** @deprecated phpdoc */
 #[CustomDeprecated()]
 function doubleDeprecatedFunctionOnlyPhpDocMessage() {}
+
+
+#[CustomDeprecated]
+enum MyDeprecatedEnum: string
+{
+	#[CustomDeprecated('custom')]
+	case CustomDeprecated = '1';
+
+	/**
+	 * @deprecated phpdoc
+	 */
+	case PhpDocDeprecated = '2';
+
+	#[\Deprecated('native')]
+	case NativeDeprecated = '3';
+
+	case NotDeprecated = '4';
+
+}
