Useful tip about what @throws should be added when the implicit one is too wide

Author: ondrejmirtes

src/Rules/Exceptions/TooWideMethodThrowTypeRule.php

@@ -2,12 +2,20 @@
 
 namespace PHPStan\Rules\Exceptions;
 
+use PhpParser\Comment\Doc;
 use PhpParser\Node;
 use PHPStan\Analyser\Scope;
 use PHPStan\Node\MethodReturnStatementsNode;
+use PHPStan\Reflection\ClassReflection;
 use PHPStan\Rules\Rule;
 use PHPStan\Rules\RuleErrorBuilder;
 use PHPStan\Type\FileTypeMapper;
+use PHPStan\Type\TypeUtils;
+use PHPStan\Type\VerbosityLevel;
+use function array_diff;
+use function array_map;
+use function count;
+use function implode;
 use function sprintf;
 
 /**
@@ -53,44 +61,60 @@ public function processNode(Node $node, Scope $scope): array
 }
 
 $unusedThrowClasses = $this->check->check($throwType, $statementResult->getThrowPoints());
-if (!$this->tooWideImplicitThrows) {
-$docComment = $node->getDocComment();
-if ($docComment === null) {
-return [];
-}
+if (count($unusedThrowClasses) === 0) {
+return [];
+}
 
-$classReflection = $node->getClassReflection();
-$resolvedPhpDoc = $this->fileTypeMapper->getResolvedPhpDoc(
-$scope->getFile(),
-$classReflection->getName(),
-$scope->isInTrait() ? $scope->getTraitReflection()->getName() : null,
-$method->getName(),
-$docComment->getText(),
-);
+$isThrowTypeExplicit = $this->isThrowTypeExplicit(
+$node->getDocComment(),
+$scope,
+$node->getClassReflection(),
+$method->getName(),
+);
 
-if ($resolvedPhpDoc->getThrowsTag() === null) {
-return [];
-}
-
-$explicitThrowType = $resolvedPhpDoc->getThrowsTag()->getType();
-if ($explicitThrowType->equals($throwType)) {
-return [];
-}
+if (!$isThrowTypeExplicit && !$this->tooWideImplicitThrows) {
+return [];
 }
 
+$throwClasses = array_map(static fn ($type) => $type->describe(VerbosityLevel::typeOnly()), TypeUtils::flattenTypes($throwType));
+$usedClasses = array_diff($throwClasses, $unusedThrowClasses);
+
 $errors = [];
 foreach ($unusedThrowClasses as $throwClass) {
-$errors[] = RuleErrorBuilder::message(sprintf(
+$builder = RuleErrorBuilder::message(sprintf(
 'Method %s::%s() has %s in PHPDoc @throws tag but it\'s not thrown.',
 $method->getDeclaringClass()->getDisplayName(),
 $method->getName(),
 $throwClass,
-))
-->identifier('throws.unusedType')
-->build();
+))->identifier('throws.unusedType');
+
+if (!$isThrowTypeExplicit) {
+$builder->tip(sprintf(
+'You can narrow the thrown type with PHPDoc tag @throws %s.',
+count($usedClasses) === 0 ? 'void' : implode('|', $usedClasses),
+));
+}
+$errors[] = $builder->build();
 }
 
 return $errors;
 }
 
+private function isThrowTypeExplicit(?Doc $docComment, Scope $scope, ClassReflection $classReflection, string $methodName): bool
+{
+if ($docComment === null) {
+return false;
+}
+
+$resolvedPhpDoc = $this->fileTypeMapper->getResolvedPhpDoc(
+$scope->getFile(),
+$classReflection->getName(),
+$scope->isInTrait() ? $scope->getTraitReflection()->getName() : null,
+$methodName,
+$docComment->getText(),
+);
+
+return $resolvedPhpDoc->getThrowsTag() !== null;
+}
+
 }

tests/PHPStan/Rules/Exceptions/TooWideMethodThrowTypeRuleTest.php

@@ -56,6 +56,7 @@ public function testRule(): void
 [
 'Method TooWideThrowsMethod\ChildClass::doFoo() has LogicException in PHPDoc @throws tag but it\'s not thrown.',
 87,
+'You can narrow the thrown type with PHPDoc tag @throws void.',
 ],
 [
 'Method TooWideThrowsMethod\ImmediatelyCalledCallback::doFoo2() has InvalidArgumentException in PHPDoc @throws tag but it\'s not thrown.',
@@ -138,6 +139,7 @@ public static function dataAlwaysCheckFinal(): iterable
 [
 'Method TooWideThrowTypeAlwaysCheckFinal\Baz::doFoo() has RuntimeException in PHPDoc @throws tag but it\'s not thrown.',
 38,
+'You can narrow the thrown type with PHPDoc tag @throws LogicException.',
 ],
 [
 'Method TooWideThrowTypeAlwaysCheckFinal\Baz::doBar() has RuntimeException in PHPDoc @throws tag but it\'s not thrown.',
@@ -171,6 +173,7 @@ public static function dataTooWideImplicitThrows(): iterable
 [
 'Method TooWideImplicitThrows\Bar::doFoo() has LogicException in PHPDoc @throws tag but it\'s not thrown.',
 23,
+'You can narrow the thrown type with PHPDoc tag @throws void.',
 ],
 ],
 ];