DeprecationExtensions: allow custom deprecation-marking logic

Author: janedbal

build/enums.neon

@@ -13,3 +13,7 @@ parameters:
 paths:
 - ../tests/PHPStan/Type/ObjectTypeTest.php
 - ../tests/PHPStan/Type/IntersectionTypeTest.php
+-
+message: '#^Class CustomDeprecations\\MyDeprecatedEnum not found\.$#'
+paths:
+- ../tests/PHPStan/Reflection/Deprecation/DeprecationProviderTest.php

conf/config.neon

@@ -2158,6 +2158,9 @@ services:
 -
 class: PHPStan\Reflection\BetterReflection\SourceStubber\ReflectionSourceStubberFactory
 
+-
+class: PHPStan\Reflection\Deprecation\DeprecationProvider
+
 php8Lexer:
 class: PhpParser\Lexer\Emulative
 factory: @PHPStan\Parser\LexerFactory::createEmulative()

src/Analyser/NodeScopeResolver.php

@@ -137,6 +137,7 @@
 use PHPStan\Reflection\Callables\SimpleImpurePoint;
 use PHPStan\Reflection\Callables\SimpleThrowPoint;
 use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\Deprecation\DeprecationProvider;
 use PHPStan\Reflection\ExtendedMethodReflection;
 use PHPStan\Reflection\ExtendedParameterReflection;
 use PHPStan\Reflection\ExtendedParametersAcceptor;
@@ -256,6 +257,7 @@ public function __construct(
 private readonly StubPhpDocProvider $stubPhpDocProvider,
 private readonly PhpVersion $phpVersion,
 private readonly SignatureMapProvider $signatureMapProvider,
+private readonly DeprecationProvider $deprecationProvider,
 private readonly AttributeReflectionFactory $attributeReflectionFactory,
 private readonly PhpDocInheritanceResolver $phpDocInheritanceResolver,
 private readonly FileHelper $fileHelper,
@@ -2193,6 +2195,7 @@ private function createAstClassReflection(Node\Stmt\ClassLike $stmt, string $cla
 $this->phpDocInheritanceResolver,
 $this->phpVersion,
 $this->signatureMapProvider,
+$this->deprecationProvider,
 $this->attributeReflectionFactory,
 $this->classReflectionExtensionRegistryProvider->getRegistry()->getPropertiesClassReflectionExtensions(),
 $this->classReflectionExtensionRegistryProvider->getRegistry()->getMethodsClassReflectionExtensions(),

src/DependencyInjection/ConditionalTagsExtension.php

@@ -16,6 +16,12 @@
 use PHPStan\Parser\RichParser;
 use PHPStan\PhpDoc\StubFilesExtension;
 use PHPStan\PhpDoc\TypeNodeResolverExtension;
+use PHPStan\Reflection\Deprecation\ClassConstantDeprecationExtension;
+use PHPStan\Reflection\Deprecation\ClassDeprecationExtension;
+use PHPStan\Reflection\Deprecation\EnumCaseDeprecationExtension;
+use PHPStan\Reflection\Deprecation\FunctionDeprecationExtension;
+use PHPStan\Reflection\Deprecation\MethodDeprecationExtension;
+use PHPStan\Reflection\Deprecation\PropertyDeprecationExtension;
 use PHPStan\Rules\Constants\AlwaysUsedClassConstantsExtensionProvider;
 use PHPStan\Rules\LazyRegistry;
 use PHPStan\Rules\Properties\ReadWritePropertiesExtensionProvider;
@@ -61,6 +67,12 @@ public function getConfigSchema(): Nette\Schema\Schema
 LazyParameterOutTypeExtensionProvider::STATIC_METHOD_TAG => $bool,
 DiagnoseExtension::EXTENSION_TAG => $bool,
 ResultCacheMetaExtension::EXTENSION_TAG => $bool,
+ClassConstantDeprecationExtension::CLASS_CONSTANT_EXTENSION_TAG => $bool,
+ClassDeprecationExtension::CLASS_EXTENSION_TAG => $bool,
+EnumCaseDeprecationExtension::ENUM_CASE_EXTENSION_TAG => $bool,
+FunctionDeprecationExtension::FUNCTION_EXTENSION_TAG => $bool,
+MethodDeprecationExtension::METHOD_EXTENSION_TAG => $bool,
+PropertyDeprecationExtension::PROPERTY_EXTENSION_TAG => $bool,
 ])->min(1));
 }
 

src/Reflection/BetterReflection/BetterReflectionProvider.php

@@ -36,6 +36,7 @@
 use PHPStan\Reflection\ClassReflection;
 use PHPStan\Reflection\Constant\RuntimeConstantReflection;
 use PHPStan\Reflection\ConstantReflection;
+use PHPStan\Reflection\Deprecation\DeprecationProvider;
 use PHPStan\Reflection\FunctionReflection;
 use PHPStan\Reflection\FunctionReflectionFactory;
 use PHPStan\Reflection\InitializerExprContext;
@@ -85,6 +86,7 @@ public function __construct(
 private Reflector $reflector,
 private FileTypeMapper $fileTypeMapper,
 private PhpDocInheritanceResolver $phpDocInheritanceResolver,
+private DeprecationProvider $deprecationProvider,
 private PhpVersion $phpVersion,
 private NativeFunctionReflectionProvider $nativeFunctionReflectionProvider,
 private StubPhpDocProvider $stubPhpDocProvider,
@@ -148,6 +150,7 @@ public function getClass(string $className): ClassReflection
 $this->phpDocInheritanceResolver,
 $this->phpVersion,
 $this->signatureMapProvider,
+$this->deprecationProvider,
 $this->attributeReflectionFactory,
 $this->classReflectionExtensionRegistryProvider->getRegistry()->getPropertiesClassReflectionExtensions(),
 $this->classReflectionExtensionRegistryProvider->getRegistry()->getMethodsClassReflectionExtensions(),
@@ -243,6 +246,7 @@ public function getAnonymousClassReflection(Node\Stmt\Class_ $classNode, Scope $
 $this->phpDocInheritanceResolver,
 $this->phpVersion,
 $this->signatureMapProvider,
+$this->deprecationProvider,
 $this->attributeReflectionFactory,
 $this->classReflectionExtensionRegistryProvider->getRegistry()->getPropertiesClassReflectionExtensions(),
 $this->classReflectionExtensionRegistryProvider->getRegistry()->getMethodsClassReflectionExtensions(),
@@ -305,8 +309,11 @@ private function getCustomFunction(string $functionName): PhpFunctionReflection
 $phpDocParameterTypes = [];
 $phpDocReturnTag = null;
 $phpDocThrowsTag = null;
-$deprecatedTag = null;
-$isDeprecated = false;
+
+$deprecation = $this->deprecationProvider->getFunctionDeprecation($reflectionFunction);
+$deprecationDescription = $deprecation === null ? null : $deprecation->getDescription();
+$isDeprecated = $deprecation !== null;
+
 $isInternal = false;
 $isPure = null;
 $asserts = Assertions::createEmpty();
@@ -327,8 +334,10 @@ private function getCustomFunction(string $functionName): PhpFunctionReflection
 $phpDocParameterTypes = array_map(static fn ($tag) => $tag->getType(), $resolvedPhpDoc->getParamTags());
 $phpDocReturnTag = $resolvedPhpDoc->getReturnTag();
 $phpDocThrowsTag = $resolvedPhpDoc->getThrowsTag();
-$deprecatedTag = $resolvedPhpDoc->getDeprecatedTag();
-$isDeprecated = $resolvedPhpDoc->isDeprecated();
+if (!$isDeprecated) {
+$deprecationDescription = $resolvedPhpDoc->getDeprecatedTag() !== null ? $resolvedPhpDoc->getDeprecatedTag()->getMessage() : $deprecationDescription;
+$isDeprecated = $resolvedPhpDoc->isDeprecated();
+}
 $isInternal = $resolvedPhpDoc->isInternal();
 $isPure = $resolvedPhpDoc->isPure();
 $asserts = Assertions::createFromResolvedPhpDocBlock($resolvedPhpDoc);
@@ -347,7 +356,7 @@ private function getCustomFunction(string $functionName): PhpFunctionReflection
 $phpDocParameterTypes,
 $phpDocReturnTag !== null ? $phpDocReturnTag->getType() : null,
 $phpDocThrowsTag !== null ? $phpDocThrowsTag->getType() : null,
-$deprecatedTag !== null ? $deprecatedTag->getMessage() : null,
+$deprecationDescription,
 $isDeprecated,
 $isInternal,
 $reflectionFunction->getFileName() !== false ? $reflectionFunction->getFileName() : null,
@@ -407,13 +416,15 @@ public function getConstant(Node\Name $nameNode, ?NamespaceAnswerer $namespaceAn
 $constantValueType = $this->initializerExprTypeResolver->getType($constantReflection->getValueExpression(), InitializerExprContext::fromGlobalConstant($constantReflection));
 $docComment = $constantReflection->getDocComment();
 
-$isDeprecated = TrinaryLogic::createNo();
-$deprecatedDescription = null;
-if ($docComment !== null) {
+$deprecation = $this->deprecationProvider->getConstantDeprecation($constantReflection);
+$isDeprecated = $deprecation !== null;
+$deprecatedDescription = $deprecation === null ? null : $deprecation->getDescription();
+
+if ($isDeprecated === false && $docComment !== null) {
 $resolvedPhpDoc = $this->fileTypeMapper->getResolvedPhpDoc($fileName, null, null, null, $docComment);
-$isDeprecated = TrinaryLogic::createFromBoolean($resolvedPhpDoc->isDeprecated());
+$isDeprecated = $resolvedPhpDoc->isDeprecated();
 
-if ($resolvedPhpDoc->isDeprecated() && $resolvedPhpDoc->getDeprecatedTag() !== null) {
+if ($isDeprecated && $resolvedPhpDoc->getDeprecatedTag() !== null) {
 $deprecatedMessage = $resolvedPhpDoc->getDeprecatedTag()->getMessage();
 
 $matches = Strings::match($deprecatedMessage ?? '', '#^(\d+)\.(\d+)(?:\.(\d+))?$#');
@@ -423,7 +434,7 @@ public function getConstant(Node\Name $nameNode, ?NamespaceAnswerer $namespaceAn
 $patch = $matches[3] ?? 0;
 $versionId = sprintf('%d%02d%02d', $major, $minor, $patch);
 
-$isDeprecated = TrinaryLogic::createFromBoolean($this->phpVersion->getVersionId() >= $versionId);
+$isDeprecated = $this->phpVersion->getVersionId() >= $versionId;
 } else {
 // filter raw version number messages like in
 // https://github.com/JetBrains/phpstorm-stubs/blob/9608c953230b08f07b703ecfe459cc58d5421437/filter/filter.php#L478
@@ -436,7 +447,7 @@ public function getConstant(Node\Name $nameNode, ?NamespaceAnswerer $namespaceAn
 $constantName,
 $constantValueType,
 $fileName,
-$isDeprecated,
+TrinaryLogic::createFromBoolean($isDeprecated),
 $deprecatedDescription,
 );
 }

src/Reflection/ClassReflection.php

@@ -26,6 +26,7 @@
 use PHPStan\PhpDoc\Tag\TemplateTag;
 use PHPStan\PhpDoc\Tag\TypeAliasImportTag;
 use PHPStan\PhpDoc\Tag\TypeAliasTag;
+use PHPStan\Reflection\Deprecation\DeprecationProvider;
 use PHPStan\Reflection\Php\PhpClassReflectionExtension;
 use PHPStan\Reflection\Php\PhpPropertyReflection;
 use PHPStan\Reflection\Php\UniversalObjectCratesClassReflectionExtension;
@@ -161,6 +162,7 @@ public function __construct(
 private PhpDocInheritanceResolver $phpDocInheritanceResolver,
 private PhpVersion $phpVersion,
 private SignatureMapProvider $signatureMapProvider,
+private DeprecationProvider $deprecationProvider,
 private AttributeReflectionFactory $attributeReflectionFactory,
 private array $propertiesClassReflectionExtensions,
 private array $methodsClassReflectionExtensions,
@@ -793,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;
@@ -819,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
@@ -1079,6 +1084,10 @@ public function getConstant(string $name): ClassConstantReflection
 throw new MissingConstantFromReflectionException($this->getName(), $name);
 }
 
+$deprecation = $this->deprecationProvider->getClassConstantDeprecation($reflectionConstant);
+$deprecatedDescription = $deprecation === null ? null : $deprecation->getDescription();
+$isDeprecated = $deprecation !== null;
+
 $declaringClass = $this->reflectionProvider->getClass($reflectionConstant->getDeclaringClass()->getName());
 $fileName = $declaringClass->getFileName();
 $phpDocType = null;
@@ -1099,8 +1108,10 @@ public function getConstant(string $name): ClassConstantReflection
 );
 }
 
-$deprecatedDescription = $resolvedPhpDoc->getDeprecatedTag() !== null ? $resolvedPhpDoc->getDeprecatedTag()->getMessage() : null;
-$isDeprecated = $resolvedPhpDoc->isDeprecated();
+if (!$isDeprecated) {
+$deprecatedDescription = $resolvedPhpDoc->getDeprecatedTag() !== null ? $resolvedPhpDoc->getDeprecatedTag()->getMessage() : null;
+$isDeprecated = $resolvedPhpDoc->isDeprecated();
+}
 $isInternal = $resolvedPhpDoc->isInternal();
 $isFinal = $resolvedPhpDoc->isFinal();
 $varTags = $resolvedPhpDoc->getVarTags();
@@ -1210,11 +1221,8 @@ public function getTypeAliases(): array
 
 public function getDeprecatedDescription(): ?string
 {
-if ($this->deprecatedDescription === null && $this->isDeprecated()) {
-$resolvedPhpDoc = $this->getResolvedPhpDoc();
-if ($resolvedPhpDoc !== null && $resolvedPhpDoc->getDeprecatedTag() !== null) {
-$this->deprecatedDescription = $resolvedPhpDoc->getDeprecatedTag()->getMessage();
-}
+if ($this->isDeprecated === null) {
+$this->resolveDeprecation();
 }
 
 return $this->deprecatedDescription;
@@ -1223,13 +1231,36 @@ public function getDeprecatedDescription(): ?string
 public function isDeprecated(): bool
 {
 if ($this->isDeprecated === null) {
-$resolvedPhpDoc = $this->getResolvedPhpDoc();
-$this->isDeprecated = $resolvedPhpDoc !== null && $resolvedPhpDoc->isDeprecated();
+$this->resolveDeprecation();
 }
 
 return $this->isDeprecated;
 }
 
+/**
+ * @phpstan-assert bool $this->isDeprecated
+ */
+private function resolveDeprecation(): void
+{
+$deprecation = $this->deprecationProvider->getClassDeprecation($this->reflection);
+if ($deprecation !== null) {
+$this->isDeprecated = true;
+$this->deprecatedDescription = $deprecation->getDescription();
+return;
+}
+
+$resolvedPhpDoc = $this->getResolvedPhpDoc();
+
+if ($resolvedPhpDoc !== null && $resolvedPhpDoc->isDeprecated()) {
+$this->isDeprecated = true;
+$this->deprecatedDescription = $resolvedPhpDoc->getDeprecatedTag() !== null ? $resolvedPhpDoc->getDeprecatedTag()->getMessage() : null;
+return;
+}
+
+$this->isDeprecated = false;
+$this->deprecatedDescription = null;
+}
+
 public function isBuiltin(): bool
 {
 return $this->reflection->isInternal();
@@ -1559,6 +1590,7 @@ public function withTypes(array $types): self
 $this->phpDocInheritanceResolver,
 $this->phpVersion,
 $this->signatureMapProvider,
+$this->deprecationProvider,
 $this->attributeReflectionFactory,
 $this->propertiesClassReflectionExtensions,
 $this->methodsClassReflectionExtensions,
@@ -1590,6 +1622,7 @@ public function withVariances(array $variances): self
 $this->phpDocInheritanceResolver,
 $this->phpVersion,
 $this->signatureMapProvider,
+$this->deprecationProvider,
 $this->attributeReflectionFactory,
 $this->propertiesClassReflectionExtensions,
 $this->methodsClassReflectionExtensions,
@@ -1631,6 +1664,7 @@ public function asFinal(): self
 $this->phpDocInheritanceResolver,
 $this->phpVersion,
 $this->signatureMapProvider,
+$this->deprecationProvider,
 $this->attributeReflectionFactory,
 $this->propertiesClassReflectionExtensions,
 $this->methodsClassReflectionExtensions,

src/Reflection/Deprecation/ClassConstantDeprecationExtension.php

@@ -0,0 +1,29 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Reflection\Deprecation;
+
+use PHPStan\BetterReflection\Reflection\Adapter\ReflectionClassConstant;
+
+/**
+ * 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.classConstantDeprecationExtension
+ * ```
+ *
+ * @api
+ */
+interface ClassConstantDeprecationExtension
+{
+
+public const CLASS_CONSTANT_EXTENSION_TAG = 'phpstan.classConstantDeprecationExtension';
+
+public function getClassConstantDeprecation(ReflectionClassConstant $reflection): ?Deprecation;
+
+}

src/Reflection/Deprecation/ClassDeprecationExtension.php

@@ -0,0 +1,30 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Reflection\Deprecation;
+
+use PHPStan\BetterReflection\Reflection\Adapter\ReflectionClass;
+use PHPStan\BetterReflection\Reflection\Adapter\ReflectionEnum;
+
+/**
+ * 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.classDeprecationExtension
+ * ```
+ *
+ * @api
+ */
+interface ClassDeprecationExtension
+{
+
+public const CLASS_EXTENSION_TAG = 'phpstan.classDeprecationExtension';
+
+public function getClassDeprecation(ReflectionClass|ReflectionEnum $reflection): ?Deprecation;
+
+}