Collect dependencies defined in @throws docblock tags (#513)

micheleorselli · claude · fain182 · web-flow · commit a8ff5105cbfb · 2026-02-17T12:36:35.000+01:00
Co-Authored-By: Claude Sonnet 4.5 &lt;noreply@anthropic.com&gt;
Co-authored-by: Pietro Campagnano &lt;hello@pietro.camp&gt;
Co-authored-by: Claude Haiku 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/src/Analyzer/Docblock.php b/src/Analyzer/Docblock.php
@@ -43,6 +43,23 @@ public function getReturnTagTypes(): array
         return array_filter($returnTypes);
     }
 
+    /**
+     * @return array<array{type: string, line: int}>
+     */
+    public function getThrowTagsTypes(): array
+    {
+        $throwTypes = [];
+
+        foreach ($this->phpDocNode->getThrowsTagValues() as $throwTag) {
+            $type = $this->getType($throwTag->type);
+            if (null !== $type) {
+                $throwTypes[] = ['type' => $type, 'line' => $throwTag->getAttribute('startLine') ?? 0];
+            }
+        }
+
+        return $throwTypes;
+    }
+
     public function getVarTagTypes(): array
     {
         $varTypes = array_map(
diff --git a/src/Analyzer/DocblockParserFactory.php b/src/Analyzer/DocblockParserFactory.php
@@ -22,7 +22,7 @@ public static function create(): DocblockParser
 
         // this if is to allow using v 1.2 or v2
         if (class_exists(ParserConfig::class)) {
-            $parserConfig = new ParserConfig([]);
+            $parserConfig = new ParserConfig(['lines' => true]);
             $constExprParser = new ConstExprParser($parserConfig);
             $typeParser = new TypeParser($parserConfig, $constExprParser);
             $phpDocParser = new PhpDocParser($parserConfig, $typeParser, $constExprParser);
diff --git a/src/Analyzer/DocblockTypesResolver.php b/src/Analyzer/DocblockTypesResolver.php
@@ -25,6 +25,8 @@
  */
 class DocblockTypesResolver extends NodeVisitorAbstract
 {
+    public const THROWS_TYPES_ATTRIBUTE = 'docblock_throws_types';
+
     private NameContext $nameContext;
 
     private bool $parseCustomAnnotations;
@@ -117,6 +119,18 @@ private function resolveFunctionTypes(Node $node): void
             return;
         }
 
+        $this->resolveParamTypes($node, $docblock);
+
+        $this->resolveReturnValueType($node, $docblock);
+
+        $this->resolveThrowsValueType($node, $docblock);
+    }
+
+    /**
+     * @param Stmt\ClassMethod|Stmt\Function_|Expr\Closure|Expr\ArrowFunction $node
+     */
+    private function resolveParamTypes(Node $node, Docblock $docblock): void
+    {
         // extract param types from param tags
         foreach ($node->params as $param) {
             if (!$this->isTypeArray($param->type)) { // not an array, nothing to do
@@ -136,19 +150,62 @@ private function resolveFunctionTypes(Node $node): void
 
             $param->type = $this->resolveName(new Name($type), Stmt\Use_::TYPE_NORMAL);
         }
+    }
 
-        // extract return type from return tag
-        if ($this->isTypeArray($node->returnType)) {
-            $type = $docblock->getReturnTagTypes();
-            $type = array_pop($type);
+    /**
+     * @param Stmt\ClassMethod|Stmt\Function_|Expr\Closure|Expr\ArrowFunction $node
+     */
+    private function resolveReturnValueType(Node $node, Docblock $docblock): void
+    {
+        if (null === $node->returnType) {
+            return;
+        }
 
-            // we ignore any type which is not a class
-            if (!$this->isTypeClass($type)) {
-                return;
+        if (!$this->isTypeArray($node->returnType)) {
+            return;
+        }
+
+        $type = $docblock->getReturnTagTypes();
+        $type = array_pop($type);
+
+        // we ignore any type which is not a class
+        if (!$this->isTypeClass($type)) {
+            return;
+        }
+
+        $node->returnType = $this->resolveName(new Name($type), Stmt\Use_::TYPE_NORMAL);
+    }
+
+    /**
+     * @param Stmt\ClassMethod|Stmt\Function_|Expr\Closure|Expr\ArrowFunction $node
+     */
+    private function resolveThrowsValueType(Node $node, Docblock $docblock): void
+    {
+        // extract throw types from throw tag
+        $throwValues = $docblock->getThrowTagsTypes();
+
+        if (empty($throwValues)) {
+            return;
+        }
+
+        $docComment = $node->getDocComment();
+        $docblockStartLine = $docComment ? $docComment->getStartLine() : $node->getStartLine();
+
+        $throwsTypesResolved = [];
+
+        foreach ($throwValues as ['type' => $throwValue, 'line' => $relativeLine]) {
+            if (str_starts_with($throwValue, '\\')) {
+                $name = new FullyQualified(substr($throwValue, 1));
+            } else {
+                $name = $this->resolveName(new Name($throwValue), Stmt\Use_::TYPE_NORMAL);
             }
 
-            $node->returnType = $this->resolveName(new Name($type), Stmt\Use_::TYPE_NORMAL);
+            $name->setAttribute('startLine', $docblockStartLine + $relativeLine - 1);
+
+            $throwsTypesResolved[] = $name;
         }
+
+        $node->setAttribute(self::THROWS_TYPES_ATTRIBUTE, $throwsTypesResolved);
     }
 
     /**
diff --git a/src/Analyzer/FileVisitor.php b/src/Analyzer/FileVisitor.php
@@ -73,6 +73,9 @@ public function enterNode(Node $node): void
 
         // handles property hooks like public string $name { get => ...; set { ... } }
         $this->handlePropertyHookNode($node);
+
+        // handles throws types like @throws MyClass
+        $this->handleThrowsTags($node);
     }
 
     public function getClassDescriptions(): array
@@ -352,6 +355,19 @@ private function handleAttributeNode(Node $node): void
             ->addAttribute($node->name->toString(), $node->getLine());
     }
 
+    private function handleThrowsTags(Node $node): void
+    {
+        if (!$node->hasAttribute(DocblockTypesResolver::THROWS_TYPES_ATTRIBUTE)) {
+            return;
+        }
+
+        /** @var Node\Name\FullyQualified $throw */
+        foreach ($node->getAttribute(DocblockTypesResolver::THROWS_TYPES_ATTRIBUTE) as $throw) {
+            $this->classDescriptionBuilder
+                ->addDependency(new ClassDependency($throw->toString(), $throw->getLine()));
+        }
+    }
+
     private function addParamDependency(Node\Param $node): void
     {
         if (null === $node->type || $node->type instanceof Node\Identifier) {
diff --git a/tests/Unit/Analyzer/DocblockParserTest.php b/tests/Unit/Analyzer/DocblockParserTest.php
@@ -98,6 +98,30 @@ public function test_it_should_extract_types_from_var_tag(): void
         self::assertEquals('(int | string)', $varTags[6]);
     }
 
+    public function test_it_should_extract_types_from_throws_tag(): void
+    {
+        $parser = DocblockParserFactory::create();
+
+        $code = <<< 'PHP'
+            /**
+             * @throws \Exception
+             * @throws \Domain\Foo\FooException
+             * @throws BarException
+             */
+        PHP;
+
+        $db = $parser->parse($code);
+
+        $varTags = $db->getThrowTagsTypes();
+        self::assertCount(3, $varTags);
+        self::assertEquals('\Exception', $varTags[0]['type']);
+        self::assertEquals('\Domain\Foo\FooException', $varTags[1]['type']);
+        self::assertEquals('BarException', $varTags[2]['type']);
+        self::assertEquals(2, $varTags[0]['line']);
+        self::assertEquals(3, $varTags[1]['line']);
+        self::assertEquals(4, $varTags[2]['line']);
+    }
+
     public function test_it_should_extract_doctrine_like_annotations(): void
     {
         $parser = DocblockParserFactory::create();
diff --git a/tests/Unit/Analyzer/DocblockTypesResolverTest.php b/tests/Unit/Analyzer/DocblockTypesResolverTest.php
@@ -78,8 +78,14 @@ public function myMethod(array $users, array $products, MyOtherClass $other): vo
              * @param array<int, User> $users
              *
              * @return array<int, int|string>
+             *
+             * @throws \Exception
+             * @throws \Domain\Foo\FooException
+             * @throws BarException
              */
             public function myMethod2(array $aParam, array $users): array
+            {
+            }
         }
         EOF;
 
@@ -88,7 +94,7 @@ public function myMethod2(array $aParam, array $users): array
         $cd = $parser->getClassDescriptions()[0];
         $dep = $cd->getDependencies();
 
-        self::assertCount(9, $cd->getDependencies());
+        self::assertCount(11, $cd->getDependencies());
         self::assertEquals('Application\Model\User', $dep[0]->getFQCN()->toString());
         self::assertEquals('Symfony\Component\Validator\Constraints\NotBlank', $dep[1]->getFQCN()->toString());
         self::assertEquals('UuidFactoryInterface', $dep[2]->getFQCN()->toString());
@@ -97,6 +103,10 @@ public function myMethod2(array $aParam, array $users): array
         self::assertEquals('Application\Model\User', $dep[5]->getFQCN()->toString());
         self::assertEquals('Application\Model\Product', $dep[6]->getFQCN()->toString());
         self::assertEquals('Domain\Foo\MyOtherClass', $dep[7]->getFQCN()->toString());
-        self::assertEquals('Application\Model\User', $dep[8]->getFQCN()->toString());
+        self::assertEquals('Domain\Foo\FooException', $dep[8]->getFQCN()->toString());
+        self::assertEquals(55, $dep[8]->getLine());
+        self::assertEquals('Domain\Foo\BarException', $dep[9]->getFQCN()->toString());
+        self::assertEquals(56, $dep[9]->getLine());
+        self::assertEquals('Application\Model\User', $dep[10]->getFQCN()->toString());
     }
 }
diff --git a/tests/Unit/Analyzer/FileParser/CanParseDocblocksTest.php b/tests/Unit/Analyzer/FileParser/CanParseDocblocksTest.php
@@ -495,4 +495,87 @@ class ApplicationLevelDto
 
         self::assertCount(1, $violations);
     }
+
+    public function test_it_collects_throws_tag_as_dependencies(): void
+    {
+        $code = <<< 'EOF'
+        <?php
+
+        namespace Domain\Foo;
+
+        use Domain\FooException;
+        use Domain\BarException;
+
+        class MyClass
+        {
+            /**
+             * @throws FooException
+             * @throws BarException
+             */
+            public function method1()
+            {
+            }
+
+            /**
+             * @throws \Exception
+             */
+            public function method2()
+            {
+            }
+        }
+        EOF;
+
+        $fp = FileParserFactory::forPhpVersion(TargetPhpVersion::PHP_8_0);
+        $fp->parse($code, 'relativePathName');
+
+        $cd = $fp->getClassDescriptions();
+
+        self::assertCount(1, $cd);
+        $dependencies = $cd[0]->getDependencies();
+
+        // Should have 2 dependencies from @throws: FooException, BarException
+        // \Exception is a PHP core class and is filtered out
+        self::assertCount(2, $dependencies);
+
+        $fqcns = array_map(static fn ($dep) => $dep->getFQCN()->toString(), $dependencies);
+        self::assertContains('Domain\FooException', $fqcns);
+        self::assertContains('Domain\BarException', $fqcns);
+    }
+
+    public function test_it_collects_throws_tag_with_fully_qualified_names(): void
+    {
+        $code = <<< 'EOF'
+        <?php
+
+        namespace App\Services;
+
+        class MyService
+        {
+            /**
+             * @throws \Exception
+             * @throws \Domain\FooException
+             * @throws BarException
+             */
+            public function doSomething()
+            {
+            }
+        }
+        EOF;
+
+        $fp = FileParserFactory::forPhpVersion(TargetPhpVersion::PHP_8_1);
+        $fp->parse($code, 'relativePathName');
+
+        $cd = $fp->getClassDescriptions();
+
+        self::assertCount(1, $cd);
+        $dependencies = $cd[0]->getDependencies();
+
+        // Should have 2 dependencies from @throws
+        // \Exception is a PHP core class and is filtered out
+        self::assertCount(2, $dependencies);
+
+        $fqcns = array_map(static fn ($dep) => $dep->getFQCN()->toString(), $dependencies);
+        self::assertContains('Domain\FooException', $fqcns);
+        self::assertContains('App\Services\BarException', $fqcns);
+    }
 }
