Fix phpstan/phpstan#13325: RegexIterator returns a generic type with unknown parameters

[phpstan-bot]

Summary

When constructing a RegexIterator, PHPStan couldn't fully resolve template types. The class has three templates: TKey, TValue, and TIterator of Traversable<TKey, TValue>. Since the constructor only accepts Iterator<TKey, TValue>, TIterator can't be directly inferred and falls back to its bound Traversable<TKey, TValue>. However, the TKey/TValue template types within that bound were not being further resolved, leaving them as raw template type placeholders.

Changes

• Modified src/Analyser/Traverser/GenericTypeTemplateTraverser.php to call $traverse() on the resolved bound, so inner template types are recursively resolved
• Added regression test in tests/PHPStan/Rules/Methods/data/bug-13325.php and tests/PHPStan/Rules/Methods/ReturnTypeRuleTest.php

Root cause

In GenericTypeTemplateTraverser::traverse(), when a template type couldn't be resolved from the template type map (mapped to ErrorType), it was replaced with its bound via $type->getDefault() ?? $type->getBound(). However, this return value was not passed through $traverse(), so any template types nested inside the bound (e.g., TKey and TValue inside Traversable<TKey, TValue>) were never resolved. The fix simply wraps the return in $traverse() to continue recursive resolution.

Test

Added a rule test reproducing the exact scenario from the issue: a method returning RegexIterator<mixed, mixed, Traversable<mixed, mixed>> that creates new RegexIterator($iterator, 'string'). Before the fix, this produced a false positive about mismatched return types.

Fixes phpstan/phpstan#13325

[VincentLanglet]

This now gives

Method pocketmine\world\format\io\region\RegionWorldProvider::createRegionIterator() should return RegexIterator<mixed, string, FilesystemIterator> but returns RegexIterator<mixed, mixed, Traversable<mixed, mixed>>.  

with something like

/**
	 * @phpstan-return \RegexIterator<mixed, string, \FilesystemIterator>
	 */
	private function createRegionIterator() : \RegexIterator{
		return new \RegexIterator(
			new \FilesystemIterator('foo'),
			'bar',
			'baz'
		);
	}

PHPstan is not able to infer all TKey, TValue and TIterator types from new RegexIterator.

I think we should be able to write some code to be able to infer all three along with the change to @param TIterator $iterator but right now that's not the case.

[phpstan-bot]

Pushed. Here's a summary of the changes:

Root cause: The RegexIterator constructor stub used @param Iterator<TKey, TValue> $iterator, which only let PHPStan infer TKey and TValue from the argument, but TIterator could never be inferred — it always fell back to the bound Traversable<TKey, TValue>.

Fix: Changed @param Iterator<TKey, TValue> $iterator to @param TIterator $iterator in stubs/iterable.stub:443. This matches the pattern already used by IteratorIterator (line 205). Now when passing e.g. FilesystemIterator, PHPStan correctly infers TIterator = FilesystemIterator, and TKey/TValue are inferred from the bound relationship.

Tests:

• Updated tests/PHPStan/Rules/Methods/data/bug-13325.php with the corrected return type (Iterator instead of Traversable<mixed, mixed>) and added a FilesystemIterator test case
• Added tests/PHPStan/Analyser/nsrt/bug-13325.php with assertType verification of inferred types