Support messages on the deprecated PhpDoc tag

src/Analyser/NodeScopeResolver.php

@@ -237,7 +237,7 @@ private function processStmtNode(
 				$scope = $scope->enterDeclareStrictTypes();
 			}
 		} elseif ($stmt instanceof Node\Stmt\Function_) {
-			[$phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $isDeprecated, $isInternal, $isFinal] = $this->getPhpDocs($scope, $stmt);
+			[$phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal] = $this->getPhpDocs($scope, $stmt);
 
 			foreach ($stmt->params as $param) {
 				$this->processParamNode($param, $scope, $nodeCallback);
@@ -252,13 +252,14 @@ private function processStmtNode(
 				$phpDocParameterTypes,
 				$phpDocReturnType,
 				$phpDocThrowType,
+				$deprecatedDescription,
 				$isDeprecated,
 				$isInternal,
 				$isFinal
 			);
 			$this->processStmtNodes($stmt->stmts, $functionScope, $nodeCallback);
 		} elseif ($stmt instanceof Node\Stmt\ClassMethod) {
-			[$phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $isDeprecated, $isInternal, $isFinal] = $this->getPhpDocs($scope, $stmt);
+			[$phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal] = $this->getPhpDocs($scope, $stmt);
 
 			foreach ($stmt->params as $param) {
 				$this->processParamNode($param, $scope, $nodeCallback);
@@ -273,6 +274,7 @@ private function processStmtNode(
 				$phpDocParameterTypes,
 				$phpDocReturnType,
 				$phpDocThrowType,
+				$deprecatedDescription,
 				$isDeprecated,
 				$isInternal,
 				$isFinal
@@ -2016,6 +2018,7 @@ private function getPhpDocs(Scope $scope, Node\FunctionLike $functionLike): arra
 		$phpDocParameterTypes = [];
 		$phpDocReturnType = null;
 		$phpDocThrowType = null;
+		$deprecatedDescription = null;
 		$isDeprecated = false;
 		$isInternal = false;
 		$isFinal = false;
@@ -2071,12 +2074,13 @@ private function getPhpDocs(Scope $scope, Node\FunctionLike $functionLike): arra
 				$phpDocReturnType = $resolvedPhpDoc->getReturnTag()->getType();
 			}
 			$phpDocThrowType = $resolvedPhpDoc->getThrowsTag() !== null ? $resolvedPhpDoc->getThrowsTag()->getType() : null;
+			$deprecatedDescription = $resolvedPhpDoc->getDeprecatedTag() !== null ? $resolvedPhpDoc->getDeprecatedTag()->getMessage(): null;
 			$isDeprecated = $resolvedPhpDoc->isDeprecated();
 			$isInternal = $resolvedPhpDoc->isInternal();
 			$isFinal = $resolvedPhpDoc->isFinal();
 		}
 
-		return [$phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $isDeprecated, $isInternal, $isFinal];
+		return [$phpDocParameterTypes, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal];
 	}
 
 }

src/Analyser/Scope.php

@@ -1773,6 +1773,7 @@ public function enterTrait(ClassReflection $traitReflection): self
 	 * @param Type[] $phpDocParameterTypes
 	 * @param Type|null $phpDocReturnType
 	 * @param Type|null $throwType
+	 * @param string|null $deprecatedDescription
 	 * @param bool $isDeprecated
 	 * @param bool $isInternal
 	 * @param bool $isFinal
@@ -1783,6 +1784,7 @@ public function enterClassMethod(
 		array $phpDocParameterTypes,
 		?Type $phpDocReturnType,
 		?Type $throwType,
+		?string $deprecatedDescription,
 		bool $isDeprecated,
 		bool $isInternal,
 		bool $isFinal
@@ -1802,6 +1804,7 @@ public function enterClassMethod(
 				$this->getFunctionType($classMethod->returnType, $classMethod->returnType === null, false),
 				$phpDocReturnType,
 				$throwType,
+				$deprecatedDescription,
 				$isDeprecated,
 				$isInternal,
 				$isFinal
@@ -1835,6 +1838,7 @@ private function getRealParameterTypes(Node\FunctionLike $functionLike): array
 	 * @param Type[] $phpDocParameterTypes
 	 * @param Type|null $phpDocReturnType
 	 * @param Type|null $throwType
+	 * @param string|null $deprecatedDescription
 	 * @param bool $isDeprecated
 	 * @param bool $isInternal
 	 * @param bool $isFinal
@@ -1845,6 +1849,7 @@ public function enterFunction(
 		array $phpDocParameterTypes,
 		?Type $phpDocReturnType,
 		?Type $throwType,
+		?string $deprecatedDescription,
 		bool $isDeprecated,
 		bool $isInternal,
 		bool $isFinal
@@ -1859,6 +1864,7 @@ public function enterFunction(
 				$this->getFunctionType($function->returnType, $function->returnType === null, false),
 				$phpDocReturnType,
 				$throwType,
+				$deprecatedDescription,
 				$isDeprecated,
 				$isInternal,
 				$isFinal

src/Broker/Broker.php

@@ -463,6 +463,7 @@ public function getCustomFunction(\PhpParser\Node\Name $nameNode, ?Scope $scope)
 		$phpDocParameterTags = [];
 		$phpDocReturnTag = null;
 		$phpDocThrowsTag = null;
+		$deprecatedTag = null;
 		$isDeprecated = false;
 		$isInternal = false;
 		$isFinal = false;
@@ -473,6 +474,7 @@ public function getCustomFunction(\PhpParser\Node\Name $nameNode, ?Scope $scope)
 			$phpDocParameterTags = $resolvedPhpDoc->getParamTags();
 			$phpDocReturnTag = $resolvedPhpDoc->getReturnTag();
 			$phpDocThrowsTag = $resolvedPhpDoc->getThrowsTag();
+			$deprecatedTag = $resolvedPhpDoc->getDeprecatedTag();
 			$isDeprecated = $resolvedPhpDoc->isDeprecated();
 			$isInternal = $resolvedPhpDoc->isInternal();
 			$isFinal = $resolvedPhpDoc->isFinal();
@@ -485,6 +487,7 @@ public function getCustomFunction(\PhpParser\Node\Name $nameNode, ?Scope $scope)
 			}, $phpDocParameterTags),
 			$phpDocReturnTag !== null ? $phpDocReturnTag->getType() : null,
 			$phpDocThrowsTag !== null ? $phpDocThrowsTag->getType() : null,
+			$deprecatedTag !== null ? $deprecatedTag->getMessage() : null,
 			$isDeprecated,
 			$isInternal,
 			$isFinal,

src/PhpDoc/PhpDocNodeResolver.php

@@ -3,6 +3,7 @@
 namespace PHPStan\PhpDoc;
 
 use PHPStan\Analyser\NameScope;
+use PHPStan\PhpDoc\Tag\DeprecatedTag;
 use PHPStan\PhpDoc\Tag\MethodTag;
 use PHPStan\PhpDoc\Tag\MethodTagParameter;
 use PHPStan\PhpDoc\Tag\ParamTag;
@@ -40,6 +41,7 @@ public function resolve(PhpDocNode $phpDocNode, NameScope $nameScope): ResolvedP
 			$this->resolveParamTags($phpDocNode, $nameScope),
 			$this->resolveReturnTag($phpDocNode, $nameScope),
 			$this->resolveThrowsTags($phpDocNode, $nameScope),
+			$this->resolveDeprecatedTag($phpDocNode, $nameScope),
 			$this->resolveIsDeprecated($phpDocNode),
 			$this->resolveIsInternal($phpDocNode),
 			$this->resolveIsFinal($phpDocNode)
@@ -212,6 +214,16 @@ private function resolveThrowsTags(PhpDocNode $phpDocNode, NameScope $nameScope)
 		return new ThrowsTag(TypeCombinator::union(...$types));
 	}
 
+	private function resolveDeprecatedTag(PhpDocNode $phpDocNode, NameScope $nameScope): ?\PHPStan\PhpDoc\Tag\DeprecatedTag
+	{
+		foreach ($phpDocNode->getTagsByName('@deprecated') as $tagValue) {
+			return new DeprecatedTag((string) $tagValue->value);
+		}
+
+		return null;
+
+	}
+
 	private function resolveIsDeprecated(PhpDocNode $phpDocNode): bool
 	{
 		$deprecatedTags = $phpDocNode->getTagsByName('@deprecated');

src/PhpDoc/ResolvedPhpDocBlock.php

@@ -2,6 +2,7 @@
 
 namespace PHPStan\PhpDoc;
 
+use PHPStan\PhpDoc\Tag\DeprecatedTag;
 use PHPStan\PhpDoc\Tag\ReturnTag;
 use PHPStan\PhpDoc\Tag\ThrowsTag;
 
@@ -26,6 +27,9 @@ class ResolvedPhpDocBlock
 	/** @var \PHPStan\PhpDoc\Tag\ThrowsTag|null */
 	private $throwsTag;
 
+	/** @var \PHPStan\PhpDoc\Tag\DeprecatedTag|null */
+	private $deprecatedTag;
+
 	/** @var bool */
 	private $isDeprecated;
 
@@ -42,6 +46,7 @@ class ResolvedPhpDocBlock
 	 * @param array<string, \PHPStan\PhpDoc\Tag\ParamTag> $paramTags
 	 * @param \PHPStan\PhpDoc\Tag\ReturnTag|null $returnTag
 	 * @param \PHPStan\PhpDoc\Tag\ThrowsTag|null $throwsTags
+	 * @param \PHPStan\PhpDoc\Tag\DeprecatedTag|null $deprecatedTag
 	 * @param bool $isDeprecated
 	 * @param bool $isInternal
 	 * @param bool $isFinal
@@ -53,6 +58,7 @@ private function __construct(
 		array $paramTags,
 		?ReturnTag $returnTag,
 		?ThrowsTag $throwsTags,
+		?DeprecatedTag $deprecatedTag,
 		bool $isDeprecated,
 		bool $isInternal,
 		bool $isFinal
@@ -64,6 +70,7 @@ private function __construct(
 		$this->paramTags = $paramTags;
 		$this->returnTag = $returnTag;
 		$this->throwsTag = $throwsTags;
+		$this->deprecatedTag = $deprecatedTag;
 		$this->isDeprecated = $isDeprecated;
 		$this->isInternal = $isInternal;
 		$this->isFinal = $isFinal;
@@ -76,6 +83,7 @@ private function __construct(
 	 * @param array<string, \PHPStan\PhpDoc\Tag\ParamTag> $paramTags
 	 * @param \PHPStan\PhpDoc\Tag\ReturnTag|null $returnTag
 	 * @param \PHPStan\PhpDoc\Tag\ThrowsTag|null $throwsTag
+	 * @param \PHPStan\PhpDoc\Tag\DeprecatedTag|null $deprecatedTag
 	 * @param bool $isDeprecated
 	 * @param bool $isInternal
 	 * @param bool $isFinal
@@ -88,6 +96,7 @@ public static function create(
 		array $paramTags,
 		?ReturnTag $returnTag,
 		?ThrowsTag $throwsTag,
+		?DeprecatedTag $deprecatedTag,
 		bool $isDeprecated,
 		bool $isInternal,
 		bool $isFinal
@@ -100,6 +109,7 @@ public static function create(
 			$paramTags,
 			$returnTag,
 			$throwsTag,
+			$deprecatedTag,
 			$isDeprecated,
 			$isInternal,
 			$isFinal
@@ -108,7 +118,7 @@ public static function create(
 
 	public static function createEmpty(): self
 	{
-		return new self([], [], [], [], null, null, false, false, false);
+		return new self([], [], [], [], null, null, null, false, false, false);
 	}
 
 
@@ -154,6 +164,11 @@ public function getThrowsTag(): ?\PHPStan\PhpDoc\Tag\ThrowsTag
 		return $this->throwsTag;
 	}
 
+	public function getDeprecatedTag(): ?\PHPStan\PhpDoc\Tag\DeprecatedTag
+	{
+		return $this->deprecatedTag;
+	}
+
 	public function isDeprecated(): bool
 	{
 		return $this->isDeprecated;
@@ -182,6 +197,7 @@ public static function __set_state(array $properties): self
 			$properties['paramTags'],
 			$properties['returnTag'],
 			$properties['throwsTag'],
+			$properties['deprecatedTag'],
 			$properties['isDeprecated'],
 			$properties['isInternal'],
 			$properties['isFinal']

src/PhpDoc/Tag/DeprecatedTag.php

@@ -0,0 +1,32 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\PhpDoc\Tag;
+
+class DeprecatedTag
+{
+
+	/** @var string */
+	private $message;
+
+	public function __construct(string $message)
+	{
+		$this->message = $message;
+	}
+
+	public function getMessage(): string
+	{
+		return $this->message;
+	}
+
+	/**
+	 * @param mixed[] $properties
+	 * @return DeprecatedTag
+	 */
+	public static function __set_state(array $properties): self
+	{
+		return new self(
+			$properties['message']
+		);
+	}
+
+}

src/Reflection/ClassConstantReflection.php

@@ -11,6 +11,9 @@ class ClassConstantReflection implements ConstantReflection, DeprecatableReflect
 	/** @var \ReflectionClassConstant */
 	private $reflection;
 
+	/** @var string */
+	private $deprecatedDescription;
+
 	/** @var bool */
 	private $isDeprecated;
 
@@ -20,12 +23,14 @@ class ClassConstantReflection implements ConstantReflection, DeprecatableReflect
 	public function __construct(
 		ClassReflection $declaringClass,
 		\ReflectionClassConstant $reflection,
+		?string $deprecatedDescription,
 		bool $isDeprecated,
 		bool $isInternal
 	)
 	{
 		$this->declaringClass = $declaringClass;
 		$this->reflection = $reflection;
+		$this->deprecatedDescription = $deprecatedDescription;
 		$this->isDeprecated = $isDeprecated;
 		$this->isInternal = $isInternal;
 	}
@@ -68,6 +73,11 @@ public function isDeprecated(): bool
 		return $this->isDeprecated;
 	}
 
+	public function getDeprecatedDescription(): ?string
+	{
+		return $this->deprecatedDescription;
+	}
+
 	public function isInternal(): bool
 	{
 		return $this->isInternal;

src/Reflection/ClassReflection.php

@@ -44,6 +44,9 @@ class ClassReflection implements DeprecatableReflection, InternableReflection, F
 	/** @var int[]|null */
 	private $classHierarchyDistances;
 
+	/** @var string */
+	private $deprecatedDescription;
+
 	/** @var bool|null */
 	private $isDeprecated;
 
@@ -398,6 +401,7 @@ public function getConstant(string $name): ConstantReflection
 				throw new \PHPStan\Reflection\MissingConstantFromReflectionException($this->getName(), $name, $fileName !== false ? $fileName : null);
 			}
 
+			$deprecatedTag = null;
 			$isDeprecated = false;
 			$isInternal = false;
 			if ($reflectionConstant->getDocComment() !== false && $this->getFileName() !== false) {
@@ -406,13 +410,15 @@ public function getConstant(string $name): ConstantReflection
 				$className = $reflectionConstant->getDeclaringClass()->getName();
 				$resolvedPhpDoc = $this->fileTypeMapper->getResolvedPhpDoc($fileName, $className, null, $docComment);
 
+				$deprecatedDescription = $resolvedPhpDoc->getDeprecatedTag() !== null ? $resolvedPhpDoc->getDeprecatedTag()->getMessage(): null;
 				$isDeprecated = $resolvedPhpDoc->isDeprecated();
 				$isInternal = $resolvedPhpDoc->isInternal();
 			}
 
 			$this->constants[$name] = new ClassConstantReflection(
 				$this->broker->getClass($reflectionConstant->getDeclaringClass()->getName()),
 				$reflectionConstant,
+				$deprecatedTag,
 				$isDeprecated,
 				$isInternal
 			);
@@ -440,6 +446,16 @@ private function getTraitNames(): array
 		return $traitNames;
 	}
 
+	public function getDeprecatedDescription(): ?string
+	{
+		if ($this->deprecatedDescription === null) {
+			$resolvedPhpDoc = $this->getResolvedPhpDoc();
+			$this->deprecatedDescription = ($resolvedPhpDoc !== null && $resolvedPhpDoc->getDeprecatedTag()) ? $resolvedPhpDoc->getDeprecatedTag()->getMessage() : null;
+		}
+
+		return $this->deprecatedDescription;
+	}
+
 	public function isDeprecated(): bool
 	{
 		if ($this->isDeprecated === null) {

src/Reflection/DeprecatableReflection.php

@@ -7,4 +7,6 @@ interface DeprecatableReflection
 
 	public function isDeprecated(): bool;
 
+	public function getDeprecatedDescription(): ?string;
+
 }

src/Reflection/FunctionReflectionFactory.php

@@ -13,6 +13,7 @@ interface FunctionReflectionFactory
 	 * @param \PHPStan\Type\Type[] $phpDocParameterTypes
 	 * @param Type|null $phpDocReturnType
 	 * @param Type|null $phpDocThrowType
+	 * @param string|null $deprecatedDescription
 	 * @param bool $isDeprecated
 	 * @param bool $isInternal
 	 * @param bool $isFinal
@@ -24,6 +25,7 @@ public function create(
 		array $phpDocParameterTypes,
 		?Type $phpDocReturnType,
 		?Type $phpDocThrowType,
+		?string $deprecatedDescription,
 		bool $isDeprecated,
 		bool $isInternal,
 		bool $isFinal,