Fix stub @param types not applied inside method bodies

NodeScopeResolver::getPhpDocs() was only consulting FileTypeMapper
(the source file's phpDoc) when resolving parameter types inside method
bodies, never checking StubPhpDocProvider for stub overrides.

This was a regression introduced in 2.1.38 by PR #4829, which rewrote
PhpDocInheritanceResolver::resolvePhpDocForMethod() and removed the
PhpDocBlock::docBlockToResolvedDocBlock() helper that previously called
StubPhpDocProvider::findMethodPhpDoc() first.

The fix mirrors the pre-regression behaviour: consult StubPhpDocProvider
before falling back to FileTypeMapper in the ClassMethod phpDoc
resolution path of getPhpDocs().

Fixes phpstan/phpstan#14118

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mglaman

src/Analyser/NodeScopeResolver.php

@@ -137,6 +137,7 @@
 use PHPStan\Php\PhpVersion;
 use PHPStan\PhpDoc\PhpDocInheritanceResolver;
 use PHPStan\PhpDoc\ResolvedPhpDocBlock;
+use PHPStan\PhpDoc\StubPhpDocProvider;
 use PHPStan\PhpDoc\Tag\VarTag;
 use PHPStan\Reflection\Assertions;
 use PHPStan\Reflection\Callables\CallableParametersAcceptor;
@@ -267,6 +268,7 @@ public function __construct(
 		#[AutowiredParameter(ref: '@defaultAnalysisParser')]
 		private readonly Parser $parser,
 		private readonly FileTypeMapper $fileTypeMapper,
+		private readonly StubPhpDocProvider $stubPhpDocProvider,
 		private readonly PhpVersion $phpVersion,
 		private readonly PhpDocInheritanceResolver $phpDocInheritanceResolver,
 		private readonly FileHelper $fileHelper,
@@ -7446,12 +7448,20 @@ public function getPhpDocs(Scope $scope, Node\FunctionLike|Node\Stmt\Property $n
 				return $param->var->name;
 			}, $node->getParams());
 			$currentResolvedPhpDoc = null;
-			if ($docComment !== null) {
+			if ($class !== null) {
+				$currentResolvedPhpDoc = $this->stubPhpDocProvider->findMethodPhpDoc(
+					$class,
+					$class,
+					$functionName,
+					$positionalParameterNames,
+				);
+			}
+			if ($currentResolvedPhpDoc === null && $docComment !== null) {
 				$currentResolvedPhpDoc = $this->fileTypeMapper->getResolvedPhpDoc(
 					$file,
 					$class,
 					$trait,
-					$node->name->name,
+					$functionName,
 					$docComment,
 				);
 			}

src/Testing/RuleTestCase.php

@@ -27,6 +27,7 @@
 use PHPStan\Node\DeepNodeCloner;
 use PHPStan\Php\PhpVersion;
 use PHPStan\PhpDoc\PhpDocInheritanceResolver;
+use PHPStan\PhpDoc\StubPhpDocProvider;
 use PHPStan\Reflection\ClassReflectionFactory;
 use PHPStan\Reflection\InitializerExprTypeResolver;
 use PHPStan\Rules\DirectRegistry as DirectRuleRegistry;
@@ -102,6 +103,7 @@ protected function createNodeScopeResolver(): NodeScopeResolver
 			self::getContainer()->getByType(ParameterOutTypeExtensionProvider::class),
 			$this->getParser(),
 			self::getContainer()->getByType(FileTypeMapper::class),
+			self::getContainer()->getByType(StubPhpDocProvider::class),
 			self::getContainer()->getByType(PhpVersion::class),
 			self::getContainer()->getByType(PhpDocInheritanceResolver::class),
 			self::getContainer()->getByType(FileHelper::class),

src/Testing/TypeInferenceTestCase.php

@@ -21,6 +21,7 @@
 use PHPStan\Node\InClassNode;
 use PHPStan\Php\PhpVersion;
 use PHPStan\PhpDoc\PhpDocInheritanceResolver;
+use PHPStan\PhpDoc\StubPhpDocProvider;
 use PHPStan\PhpDoc\TypeStringResolver;
 use PHPStan\Reflection\ClassReflectionFactory;
 use PHPStan\Reflection\InitializerExprTypeResolver;
@@ -77,6 +78,7 @@ protected static function createNodeScopeResolver(): NodeScopeResolver
 			$container->getByType(ParameterOutTypeExtensionProvider::class),
 			self::getParser(),
 			$container->getByType(FileTypeMapper::class),
+			$container->getByType(StubPhpDocProvider::class),
 			$container->getByType(PhpVersion::class),
 			$container->getByType(PhpDocInheritanceResolver::class),
 			$container->getByType(FileHelper::class),

tests/PHPStan/Analyser/AnalyserTest.php

@@ -22,6 +22,7 @@
 use PHPStan\Parser\RichParser;
 use PHPStan\Php\PhpVersion;
 use PHPStan\PhpDoc\PhpDocInheritanceResolver;
+use PHPStan\PhpDoc\StubPhpDocProvider;
 use PHPStan\Reflection\ClassReflectionFactory;
 use PHPStan\Reflection\InitializerExprTypeResolver;
 use PHPStan\Rules\AlwaysFailRule;
@@ -818,6 +819,7 @@ private function createAnalyser(): Analyser
 			$container->getByType(ParameterOutTypeExtensionProvider::class),
 			$this->getParser(),
 			$fileTypeMapper,
+			$container->getByType(StubPhpDocProvider::class),
 			$container->getByType(PhpVersion::class),
 			$phpDocInheritanceResolver,
 			$fileHelper,

tests/PHPStan/Analyser/Fiber/FiberNodeScopeResolverRuleTest.php

@@ -13,6 +13,7 @@
 use PHPStan\Node\DeepNodeCloner;
 use PHPStan\Php\PhpVersion;
 use PHPStan\PhpDoc\PhpDocInheritanceResolver;
+use PHPStan\PhpDoc\StubPhpDocProvider;
 use PHPStan\Reflection\ClassReflectionFactory;
 use PHPStan\Reflection\InitializerExprTypeResolver;
 use PHPStan\Rules\IdentifierRuleError;
@@ -122,6 +123,7 @@ protected function createNodeScopeResolver(): NodeScopeResolver
 			self::getContainer()->getByType(ParameterOutTypeExtensionProvider::class),
 			$this->getParser(),
 			self::getContainer()->getByType(FileTypeMapper::class),
+			self::getContainer()->getByType(StubPhpDocProvider::class),
 			self::getContainer()->getByType(PhpVersion::class),
 			self::getContainer()->getByType(PhpDocInheritanceResolver::class),
 			self::getContainer()->getByType(FileHelper::class),

tests/PHPStan/Analyser/Fiber/FiberNodeScopeResolverTest.php

@@ -11,6 +11,7 @@
 use PHPStan\Node\DeepNodeCloner;
 use PHPStan\Php\PhpVersion;
 use PHPStan\PhpDoc\PhpDocInheritanceResolver;
+use PHPStan\PhpDoc\StubPhpDocProvider;
 use PHPStan\Reflection\ClassReflectionFactory;
 use PHPStan\Reflection\InitializerExprTypeResolver;
 use PHPStan\Rules\Properties\ReadWritePropertiesExtensionProvider;
@@ -55,6 +56,7 @@ protected static function createNodeScopeResolver(): NodeScopeResolver
 			$container->getByType(ParameterOutTypeExtensionProvider::class),
 			self::getParser(),
 			$container->getByType(FileTypeMapper::class),
+			$container->getByType(StubPhpDocProvider::class),
 			$container->getByType(PhpVersion::class),
 			$container->getByType(PhpDocInheritanceResolver::class),
 			$container->getByType(FileHelper::class),

tests/PHPStan/Analyser/StubMethodBodyTypesTest.php

@@ -0,0 +1,36 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Analyser;
+
+use PHPStan\Testing\TypeInferenceTestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+class StubMethodBodyTypesTest extends TypeInferenceTestCase
+{
+
+	public static function dataFileAsserts(): iterable
+	{
+		yield from self::gatherAssertTypes(__DIR__ . '/data/stub-method-body-types.php');
+	}
+
+	/**
+	 * @param mixed ...$args
+	 */
+	#[DataProvider('dataFileAsserts')]
+	public function testFileAsserts(
+		string $assertType,
+		string $file,
+		...$args,
+	): void
+	{
+		$this->assertFileAsserts($assertType, $file, ...$args);
+	}
+
+	public static function getAdditionalConfigFiles(): array
+	{
+		return [
+			__DIR__ . '/data/stub-method-body-types.neon',
+		];
+	}
+
+}

tests/PHPStan/Analyser/data/stub-method-body-types.neon

@@ -0,0 +1,3 @@
+parameters:
+	stubFiles:
+		- stub-method-body-types.stub

tests/PHPStan/Analyser/data/stub-method-body-types.php

@@ -0,0 +1,27 @@
+<?php
+
+use function PHPStan\Testing\assertType;
+
+class StubMethodBodyTypesClass
+{
+	/**
+	 * Source declares @param string — stub overrides to @param callable-string
+	 * @param string $callback
+	 * @return string
+	 */
+	public function process($callback): string
+	{
+		// Stub should override the source file's @param type inside the method body
+		assertType('callable-string', $callback);
+		return $callback;
+	}
+}
+
+class StubMethodBodyTypesExternalCaller
+{
+	public function test(StubMethodBodyTypesClass $obj): void
+	{
+		// Stub should also work for external callers (already worked before regression)
+		assertType('non-empty-string', $obj->process('strlen'));
+	}
+}

tests/PHPStan/Analyser/data/stub-method-body-types.stub

@@ -0,0 +1,10 @@
+<?php
+
+class StubMethodBodyTypesClass
+{
+	/**
+	 * @param callable-string $callback
+	 * @return non-empty-string
+	 */
+	public function process($callback): string {}
+}