Add ability to provide custom deprecations (e.g. based on custom attributes)

rules.neon

@@ -19,6 +19,16 @@ services:
 	-
 		class: PHPStan\Rules\Deprecations\CallWithDeprecatedIniOptionRule
 
+	-
+		class: PHPStan\Rules\Deprecations\DeprecationHelper
+		arguments:
+			providers: tagged(phpstan.deprecationProvider)
+
+	-
+		class: PHPStan\Rules\Deprecations\DefaultDeprecationProvider
+		tags:
+			- phpstan.deprecationProvider
+
 rules:
 	- PHPStan\Rules\Deprecations\AccessDeprecatedPropertyRule
 	- PHPStan\Rules\Deprecations\AccessDeprecatedStaticPropertyRule

src/Rules/Deprecations/AccessDeprecatedPropertyRule.php

@@ -24,10 +24,13 @@ class AccessDeprecatedPropertyRule implements Rule
 
 	private DeprecatedScopeHelper $deprecatedScopeHelper;
 
-	public function __construct(ReflectionProvider $reflectionProvider, DeprecatedScopeHelper $deprecatedScopeHelper)
+	private DeprecationHelper $deprecationHelper;
+
+	public function __construct(ReflectionProvider $reflectionProvider, DeprecatedScopeHelper $deprecatedScopeHelper, DeprecationHelper $deprecationHelper)
 	{
 		$this->reflectionProvider = $reflectionProvider;
 		$this->deprecatedScopeHelper = $deprecatedScopeHelper;
+		$this->deprecationHelper = $deprecationHelper;
 	}
 
 	public function getNodeType(): string
@@ -54,8 +57,10 @@ public function processNode(Node $node, Scope $scope): array
 				$classReflection = $this->reflectionProvider->getClass($referencedClass);
 				$propertyReflection = $classReflection->getProperty($propertyName, $scope);
 
-				if ($propertyReflection->isDeprecated()->yes()) {
-					$description = $propertyReflection->getDeprecatedDescription();
+				$deprecation = $this->deprecationHelper->getDeprecation($propertyReflection);
+
+				if ($deprecation !== null) {
+					$description = $deprecation->getDescription();
 					if ($description === null) {
 						return [
 							RuleErrorBuilder::message(sprintf(

src/Rules/Deprecations/AccessDeprecatedStaticPropertyRule.php

@@ -30,11 +30,14 @@ class AccessDeprecatedStaticPropertyRule implements Rule
 
 	private DeprecatedScopeHelper $deprecatedScopeHelper;
 
-	public function __construct(ReflectionProvider $reflectionProvider, RuleLevelHelper $ruleLevelHelper, DeprecatedScopeHelper $deprecatedScopeHelper)
+	private DeprecationHelper $deprecationHelper;
+
+	public function __construct(ReflectionProvider $reflectionProvider, RuleLevelHelper $ruleLevelHelper, DeprecatedScopeHelper $deprecatedScopeHelper, DeprecationHelper $deprecationHelper)
 	{
 		$this->reflectionProvider = $reflectionProvider;
 		$this->ruleLevelHelper = $ruleLevelHelper;
 		$this->deprecatedScopeHelper = $deprecatedScopeHelper;
+		$this->deprecationHelper = $deprecationHelper;
 	}
 
 	public function getNodeType(): string
@@ -82,8 +85,9 @@ public function processNode(Node $node, Scope $scope): array
 				continue;
 			}
 
-			if ($property->isDeprecated()->yes()) {
-				$description = $property->getDeprecatedDescription();
+			$deprecation = $this->deprecationHelper->getDeprecation($property);
+			if ($deprecation !== null) {
+				$description = $deprecation->getDescription();
 				if ($description === null) {
 					return [
 						RuleErrorBuilder::message(sprintf(

src/Rules/Deprecations/CallToDeprecatedFunctionRule.php

@@ -22,10 +22,13 @@ class CallToDeprecatedFunctionRule implements Rule
 
 	private DeprecatedScopeHelper $deprecatedScopeHelper;
 
-	public function __construct(ReflectionProvider $reflectionProvider, DeprecatedScopeHelper $deprecatedScopeHelper)
+	private DeprecationHelper $deprecationHelper;
+
+	public function __construct(ReflectionProvider $reflectionProvider, DeprecatedScopeHelper $deprecatedScopeHelper, DeprecationHelper $deprecationHelper)
 	{
 		$this->reflectionProvider = $reflectionProvider;
 		$this->deprecatedScopeHelper = $deprecatedScopeHelper;
+		$this->deprecationHelper = $deprecationHelper;
 	}
 
 	public function getNodeType(): string
@@ -50,8 +53,9 @@ public function processNode(Node $node, Scope $scope): array
 			return [];
 		}
 
-		if ($function->isDeprecated()->yes()) {
-			$description = $function->getDeprecatedDescription();
+		$deprecation = $this->deprecationHelper->getDeprecation($function);
+		if ($deprecation !== null) {
+			$description = $deprecation->getDescription();
 			if ($description === null) {
 				return [
 					RuleErrorBuilder::message(sprintf(

src/Rules/Deprecations/CallToDeprecatedMethodRule.php

@@ -24,10 +24,13 @@ class CallToDeprecatedMethodRule implements Rule
 
 	private DeprecatedScopeHelper $deprecatedScopeHelper;
 
-	public function __construct(ReflectionProvider $reflectionProvider, DeprecatedScopeHelper $deprecatedScopeHelper)
+	private DeprecationHelper $deprecationHelper;
+
+	public function __construct(ReflectionProvider $reflectionProvider, DeprecatedScopeHelper $deprecatedScopeHelper, DeprecationHelper $deprecationHelper)
 	{
 		$this->reflectionProvider = $reflectionProvider;
 		$this->deprecatedScopeHelper = $deprecatedScopeHelper;
+		$this->deprecationHelper = $deprecationHelper;
 	}
 
 	public function getNodeType(): string
@@ -54,11 +57,12 @@ public function processNode(Node $node, Scope $scope): array
 				$classReflection = $this->reflectionProvider->getClass($referencedClass);
 				$methodReflection = $classReflection->getMethod($methodName, $scope);
 
-				if (!$methodReflection->isDeprecated()->yes()) {
+				$deprecation = $this->deprecationHelper->getDeprecation($methodReflection);
+				if ($deprecation === null) {
 					continue;
 				}
 
-				$description = $methodReflection->getDeprecatedDescription();
+				$description = $deprecation->getDescription();
 				if ($description === null) {
 					return [
 						RuleErrorBuilder::message(sprintf(

src/Rules/Deprecations/CallToDeprecatedStaticMethodRule.php

@@ -30,11 +30,14 @@ class CallToDeprecatedStaticMethodRule implements Rule
 
 	private DeprecatedScopeHelper $deprecatedScopeHelper;
 
-	public function __construct(ReflectionProvider $reflectionProvider, RuleLevelHelper $ruleLevelHelper, DeprecatedScopeHelper $deprecatedScopeHelper)
+	private DeprecationHelper $deprecationHelper;
+
+	public function __construct(ReflectionProvider $reflectionProvider, RuleLevelHelper $ruleLevelHelper, DeprecatedScopeHelper $deprecatedScopeHelper, DeprecationHelper $deprecationHelper)
 	{
 		$this->reflectionProvider = $reflectionProvider;
 		$this->ruleLevelHelper = $ruleLevelHelper;
 		$this->deprecatedScopeHelper = $deprecatedScopeHelper;
+		$this->deprecationHelper = $deprecationHelper;
 	}
 
 	public function getNodeType(): string
@@ -84,8 +87,9 @@ public function processNode(Node $node, Scope $scope): array
 				continue;
 			}
 
-			if ($class->isDeprecated()) {
-				$classDescription = $class->getDeprecatedDescription();
+			$classDeprecation = $this->deprecationHelper->getDeprecation($class);
+			if ($classDeprecation !== null) {
+				$classDescription = $classDeprecation->getDescription();
 				if ($classDescription === null) {
 					$errors[] = RuleErrorBuilder::message(sprintf(
 						'Call to method %s() of deprecated %s %s.',
@@ -104,11 +108,12 @@ public function processNode(Node $node, Scope $scope): array
 				}
 			}
 
-			if (!$methodReflection->isDeprecated()->yes()) {
+			$methodDeprecation = $this->deprecationHelper->getDeprecation($methodReflection);
+			if ($methodDeprecation === null) {
 				continue;
 			}
 
-			$description = $methodReflection->getDeprecatedDescription();
+			$description = $methodDeprecation->getDescription();
 			if ($description === null) {
 				$errors[] = RuleErrorBuilder::message(sprintf(
 					'Call to deprecated method %s() of %s %s.',

src/Rules/Deprecations/DefaultDeprecatedScopeResolver.php

@@ -7,20 +7,27 @@
 final class DefaultDeprecatedScopeResolver implements DeprecatedScopeResolver
 {
 
+	private DeprecationHelper $deprecationHelper;
+
+	public function __construct(DeprecationHelper $deprecationHelper)
+	{
+		$this->deprecationHelper = $deprecationHelper;
+	}
+
 	public function isScopeDeprecated(Scope $scope): bool
 	{
 		$class = $scope->getClassReflection();
-		if ($class !== null && $class->isDeprecated()) {
+		if ($class !== null && $this->deprecationHelper->getDeprecation($class) !== null) {
 			return true;
 		}
 
 		$trait = $scope->getTraitReflection();
-		if ($trait !== null && $trait->isDeprecated()) {
+		if ($trait !== null && $this->deprecationHelper->getDeprecation($trait) !== null) {
 			return true;
 		}
 
 		$function = $scope->getFunction();
-		if ($function !== null && $function->isDeprecated()->yes()) {
+		if ($function !== null && $this->deprecationHelper->getDeprecation($function) !== null) {
 			return true;
 		}
 

src/Rules/Deprecations/DefaultDeprecationProvider.php

@@ -0,0 +1,31 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Deprecations;
+
+use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\ConstantReflection;
+use PHPStan\Reflection\EnumCaseReflection;
+use PHPStan\Reflection\ExtendedMethodReflection;
+use PHPStan\Reflection\ExtendedPropertyReflection;
+use PHPStan\Reflection\FunctionReflection;
+
+class DefaultDeprecationProvider implements DeprecationProvider
+{
+
+	/**
+	 * @param ExtendedPropertyReflection|ExtendedMethodReflection|FunctionReflection|ClassReflection|ConstantReflection|EnumCaseReflection $reflection
+	 */
+	public function getDeprecation($reflection): ?Deprecation
+	{
+		if ($reflection instanceof ClassReflection) {
+			return $reflection->isDeprecated()
+				? Deprecation::create()->withDescription($reflection->getDeprecatedDescription())
+				: null;
+		}
+
+		return $reflection->isDeprecated()->yes()
+			? Deprecation::create()->withDescription($reflection->getDeprecatedDescription())
+			: null;
+	}
+
+}

src/Rules/Deprecations/DeprecatedClassHelper.php

@@ -12,14 +12,22 @@ class DeprecatedClassHelper
 
 	private ReflectionProvider $reflectionProvider;
 
-	public function __construct(ReflectionProvider $reflectionProvider)
+	private DeprecationHelper $deprecationHelper;
+
+	public function __construct(ReflectionProvider $reflectionProvider, DeprecationHelper $deprecationHelper)
 	{
 		$this->reflectionProvider = $reflectionProvider;
+		$this->deprecationHelper = $deprecationHelper;
 	}
 
 	public function getClassDeprecationDescription(ClassReflection $class): string
 	{
-		$description = $class->getDeprecatedDescription();
+		$deprecation = $this->deprecationHelper->getDeprecation($class);
+		if ($deprecation === null) {
+			return '.';
+		}
+
+		$description = $deprecation->getDescription();
 		if ($description === null) {
 			return '.';
 		}
@@ -41,7 +49,7 @@ public function filterDeprecatedClasses(array $referencedClasses): array
 				continue;
 			}
 
-			if (!$class->isDeprecated()) {
+			if ($this->deprecationHelper->getDeprecation($class) === null) {
 				continue;
 			}
 

src/Rules/Deprecations/Deprecation.php

@@ -0,0 +1,34 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Deprecations;
+
+/**
+ * @api
+ */
+class Deprecation
+{
+
+	private ?string $description;
+
+	private function __construct()
+	{
+	}
+
+	public static function create(): self
+	{
+		return new self();
+	}
+
+	public function withDescription(?string $description): self
+	{
+		$clone = clone $this;
+		$clone->description = $description;
+		return $clone;
+	}
+
+	public function getDescription(): ?string
+	{
+		return $this->description;
+	}
+
+}

src/Rules/Deprecations/DeprecationHelper.php

@@ -0,0 +1,41 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Deprecations;
+
+use PHPStan\Reflection\ClassConstantReflection;
+use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\ConstantReflection;
+use PHPStan\Reflection\ExtendedMethodReflection;
+use PHPStan\Reflection\ExtendedPropertyReflection;
+use PHPStan\Reflection\FunctionReflection;
+
+class DeprecationHelper
+{
+
+	/** @var list<DeprecationProvider> */
+	private array $providers;
+
+	/**
+	 * @param list<DeprecationProvider> $providers
+	 */
+	public function __construct(array $providers)
+	{
+		$this->providers = $providers;
+	}
+
+	/**
+	 * @param ExtendedPropertyReflection|ExtendedMethodReflection|FunctionReflection|ClassReflection|ConstantReflection|ClassConstantReflection $reflection
+	 */
+	public function getDeprecation($reflection): ?Deprecation
+	{
+		foreach ($this->providers as $provider) {
+			$deprecation = $provider->getDeprecation($reflection);
+			if ($deprecation !== null) {
+				return $deprecation;
+			}
+		}
+
+		return null;
+	}
+
+}

src/Rules/Deprecations/DeprecationProvider.php

@@ -0,0 +1,19 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Deprecations;
+
+use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\ConstantReflection;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Reflection\PropertyReflection;
+
+interface DeprecationProvider
+{
+
+	/**
+	 * @param PropertyReflection|MethodReflection|FunctionReflection|ClassReflection|ConstantReflection $reflection
+	 */
+	public function getDeprecation($reflection): ?Deprecation;
+
+}