Improve phpdoc parsing performance of huge stub files

- Skip PHPDoc string parsing during FileTypeMapper name scope map creation
  for doc comments that don't contain @template or type-alias tags
- During createPhpDocNodeMap(), only template tags and type alias names are
  extracted from PHPDocs, so comments without these tags don't need parsing
- Uses fast str_contains() checks on the raw doc comment string to decide
  whether to invoke the full PHPDoc parser
- For a file with 10,000 function stubs, reduces processing time from ~4s
  to ~2s by avoiding ~10,000 unnecessary PhpDocStringResolver::resolve() calls
- Added performance regression test in FileTypeMapperTest

Author: staabm

src/Type/FileTypeMapper.php

@@ -485,7 +485,7 @@ function (Node $node) use ($fileName, $lookForTrait, &$traitFound, $traitMethodA
 					|| ($node instanceof Node\PropertyHook && $node->getAttribute('propertyName') !== null)
 				) {
 					$docComment = GetLastDocComment::forNode($node);
-					if ($docComment !== null) {
+					if ($docComment !== null && $this->shouldParseDocComment($docComment)) {
 						$phpDocNode = $this->phpDocStringResolver->resolve($docComment);
 					}
 				}
@@ -751,6 +751,16 @@ private function chooseTemplateTagValueNodesByPriority(array $tags): array
 		return $resolved;
 	}
 
+	private function shouldParseDocComment(string $docComment): bool
+	{
+		return str_contains($docComment, '@template')
+			|| str_contains($docComment, '-template')
+			|| str_contains($docComment, '@phpstan-type')
+			|| str_contains($docComment, '@psalm-type')
+			|| str_contains($docComment, '@phan-type')
+			|| str_contains($docComment, 'import-type');
+	}
+
 	/**
 	 * @return array<string, true>
 	 */

tests/PHPStan/Type/FileTypeMapperTest.php

@@ -7,7 +7,12 @@
 use PHPStan\ShouldNotHappenException;
 use PHPStan\Testing\PHPStanTestCase;
 use RuntimeException;
+use function file_put_contents;
+use function microtime;
 use function realpath;
+use function sys_get_temp_dir;
+use function tempnam;
+use function unlink;
 
 class FileTypeMapperTest extends PHPStanTestCase
 {
@@ -196,6 +201,78 @@ public function testFileWithCyclicPhpDocs(): void
 		$this->assertSame('CyclicPhpDocs\Foo|iterable<CyclicPhpDocs\Foo>', $returnTag->getType()->describe(VerbosityLevel::precise()));
 	}
 
+	public function testLargeStubFileLazyPhpDocParsing(): void
+	{
+		/** @var FileTypeMapper $fileTypeMapper */
+		$fileTypeMapper = self::getContainer()->getByType(FileTypeMapper::class);
+
+		// Generate a large stub file with many PHPDoc comments, simulating
+		// WordPress-style stubs where a single file declares many functions.
+		$tmpFile = tempnam(sys_get_temp_dir(), 'phpstan_stub_perf_');
+		if ($tmpFile === false) {
+			throw new ShouldNotHappenException();
+		}
+		$tmpFile .= '.php';
+
+		try {
+			$code = "<?php declare(strict_types = 1);\n\nnamespace StubPhpDocPerformance;\n\n";
+
+			// 10000 functions with complex PHPDocs but no template/type-alias tags
+			for ($i = 1; $i <= 10000; $i++) {
+				$code .= "/**\n";
+				$code .= " * @param array<string, array<int, string>> \$param1\n";
+				$code .= " * @param callable(int, string): array<string, mixed> \$param2\n";
+				$code .= " * @param list<array{id: int, name: string, data: array<string, mixed>}> \$param3\n";
+				$code .= " * @return array<int, array{key: string, value: mixed, metadata: array<string, string>}>\n";
+				$code .= " */\n";
+				$code .= "function stub_{$i}(array \$param1, callable \$param2, array \$param3): array {}\n\n";
+			}
+
+			// A class with @template - this PHPDoc must still be parsed
+			$code .= "/**\n * @template T\n */\n";
+			$code .= "class GenericContainer\n{\n";
+			$code .= "    /** @var T */\n    private \$value;\n\n";
+			$code .= "    /** @param T \$value */\n";
+			$code .= "    public function __construct(\$value) { \$this->value = \$value; }\n\n";
+			$code .= "    /** @return T */\n";
+			$code .= "    public function getValue() { return \$this->value; }\n";
+			$code .= "}\n";
+
+			file_put_contents($tmpFile, $code);
+
+			$start = microtime(true);
+
+			// Resolve the template class - should work despite 10000 other PHPDocs in file
+			$resolved = $fileTypeMapper->getResolvedPhpDoc(
+				$tmpFile,
+				'StubPhpDocPerformance\\GenericContainer',
+				null,
+				'getValue',
+				'/** @return T */',
+			);
+
+			$elapsed = microtime(true) - $start;
+
+			$returnTag = $resolved->getReturnTag();
+			$this->assertNotNull($returnTag);
+			$this->assertSame(
+				'T (class StubPhpDocPerformance\GenericContainer, parameter)',
+				$returnTag->getType()->describe(VerbosityLevel::precise()),
+			);
+
+			// With lazy PHPDoc parsing, only PHPDocs with @template or type-alias
+			// tags are parsed during name scope map creation. Without the optimization,
+			// all 10000+ PHPDocs must be parsed, taking >2 seconds on typical hardware.
+			$this->assertLessThan(
+				3.0,
+				$elapsed,
+				'FileTypeMapper should skip PHPDoc parsing for entries without template/type-alias tags',
+			);
+		} finally {
+			@unlink($tmpFile);
+		}
+	}
+
 	public function testFilesWithIdenticalPhpDocsUsingDifferentAliases(): void
 	{
 		/** @var FileTypeMapper $fileTypeMapper */