Bleeding edge - Require generics for Iterator, IteratorAggregate, Generator

Flyingmana · web-flow · commit 97288da8e82c · 2026-02-11T09:29:26.000+01:00
diff --git a/conf/bleedingEdge.neon b/conf/bleedingEdge.neon
@@ -10,6 +10,7 @@ parameters:
 		internalTag: true
 		newStaticInAbstractClassStaticMethod: true
 		checkExtensionsForComparisonOperators: true
+		checkGenericIterableClasses: true
 		reportTooWideBool: true
 		rawMessageInBaseline: true
 		reportNestedTooWideType: false # tmp
diff --git a/conf/config.neon b/conf/config.neon
@@ -37,6 +37,7 @@ parameters:
 		internalTag: false
 		newStaticInAbstractClassStaticMethod: false
 		checkExtensionsForComparisonOperators: false
+		checkGenericIterableClasses: false
 		reportTooWideBool: false
 		rawMessageInBaseline: false
 		reportNestedTooWideType: false
diff --git a/conf/parametersSchema.neon b/conf/parametersSchema.neon
@@ -39,6 +39,7 @@ parametersSchema:
 		internalTag: bool()
 		newStaticInAbstractClassStaticMethod: bool()
 		checkExtensionsForComparisonOperators: bool()
+		checkGenericIterableClasses: bool()
 		reportTooWideBool: bool()
 		rawMessageInBaseline: bool()
 		reportNestedTooWideType: bool()
diff --git a/src/Rules/MissingTypehintCheck.php b/src/Rules/MissingTypehintCheck.php
@@ -54,6 +54,8 @@ public function __construct(
 		private bool $checkMissingCallableSignature,
 		#[AutowiredParameter(ref: '%featureToggles.skipCheckGenericClasses%')]
 		private array $skipCheckGenericClasses,
+		#[AutowiredParameter(ref: '%featureToggles.checkGenericIterableClasses%')]
+		private bool $checkGenericIterableClasses,
 	)
 	{
 	}
@@ -118,7 +120,13 @@ public function getNonGenericObjectTypesWithGenericClass(Type $type): array
 				if ($classReflection === null) {
 					return $type;
 				}
-				if (in_array($classReflection->getName(), self::ITERABLE_GENERIC_CLASS_NAMES, true)) {
+				if (
+					$classReflection->getName() === Traversable::class // already covered by getIterableTypesWithMissingValueTypehint
+					|| (
+						!$this->checkGenericIterableClasses &&
+						in_array($classReflection->getName(), self::ITERABLE_GENERIC_CLASS_NAMES, true)
+					)
+				) {
 					// checked by getIterableTypesWithMissingValueTypehint() already
 					return $type;
 				}
diff --git a/stubs/PDOStatement.stub b/stubs/PDOStatement.stub
@@ -21,7 +21,7 @@ class PDOStatement implements Traversable, IteratorAggregate
     public function getColumnMeta(int $column) {}
 
     /**
-     * @return Iterator
+     * @return Iterator<mixed, array<int|string, mixed>>
      */
     public function getIterator() {}
 }
diff --git a/stubs/runtime/ReflectionAttribute.php b/stubs/runtime/ReflectionAttribute.php
@@ -22,6 +22,9 @@ public function isRepeated(): bool
 		{
 		}
 
+		/**
+		 * @return array<array-key, mixed>
+		 */
 		public function getArguments(): array
 		{
 		}
diff --git a/tests/PHPStan/Analyser/nsrt/bug-8886.php b/tests/PHPStan/Analyser/nsrt/bug-8886.php
@@ -9,5 +9,5 @@ function testPDOStatementGetIterator(): void {
 	$pdo = new PDO('sqlite::memory:');
     $stmt = $pdo->query('SELECT 1');
 
-	assertType('Iterator', $stmt->getIterator());
+	assertType('Iterator<mixed, array<int|string, mixed>>', $stmt->getIterator());
 }
diff --git a/tests/PHPStan/Rules/Classes/LocalTypeAliasesRuleTest.php b/tests/PHPStan/Rules/Classes/LocalTypeAliasesRuleTest.php
@@ -29,7 +29,7 @@ protected function getRule(): Rule
 				['GlobalTypeAlias' => 'int|string'],
 				self::createReflectionProvider(),
 				$container->getByType(TypeNodeResolver::class),
-				new MissingTypehintCheck(true, []),
+				new MissingTypehintCheck(true, [], true),
 				new ClassNameCheck(
 					new ClassCaseSensitivityCheck($reflectionProvider, true),
 					new ClassForbiddenNameCheck($container),
diff --git a/tests/PHPStan/Rules/Classes/LocalTypeTraitAliasesRuleTest.php b/tests/PHPStan/Rules/Classes/LocalTypeTraitAliasesRuleTest.php
@@ -28,7 +28,7 @@ protected function getRule(): Rule
 				['GlobalTypeAlias' => 'int|string'],
 				self::createReflectionProvider(),
 				$container->getByType(TypeNodeResolver::class),
-				new MissingTypehintCheck(true, []),
+				new MissingTypehintCheck(true, [], true),
 				new ClassNameCheck(
 					new ClassCaseSensitivityCheck($reflectionProvider, true),
 					new ClassForbiddenNameCheck($container),
diff --git a/tests/PHPStan/Rules/Classes/LocalTypeTraitUseAliasesRuleTest.php b/tests/PHPStan/Rules/Classes/LocalTypeTraitUseAliasesRuleTest.php
@@ -28,7 +28,7 @@ protected function getRule(): Rule
 				['GlobalTypeAlias' => 'int|string'],
 				self::createReflectionProvider(),
 				$container->getByType(TypeNodeResolver::class),
-				new MissingTypehintCheck(true, []),
+				new MissingTypehintCheck(true, [], true),
 				new ClassNameCheck(
 					new ClassCaseSensitivityCheck($reflectionProvider, true),
 					new ClassForbiddenNameCheck($container),
diff --git a/tests/PHPStan/Rules/Classes/MethodTagRuleTest.php b/tests/PHPStan/Rules/Classes/MethodTagRuleTest.php
@@ -32,7 +32,7 @@ protected function getRule(): TRule
 					$container,
 				),
 				new GenericObjectTypeCheck(),
-				new MissingTypehintCheck(true, []),
+				new MissingTypehintCheck(true, [], true),
 				new UnresolvableTypeHelper(),
 				true,
 				true,
diff --git a/tests/PHPStan/Rules/Classes/MethodTagTraitRuleTest.php b/tests/PHPStan/Rules/Classes/MethodTagTraitRuleTest.php
@@ -32,7 +32,7 @@ protected function getRule(): TRule
 					$container,
 				),
 				new GenericObjectTypeCheck(),
-				new MissingTypehintCheck(true, []),
+				new MissingTypehintCheck(true, [], true),
 				new UnresolvableTypeHelper(),
 				true,
 				true,
diff --git a/tests/PHPStan/Rules/Classes/MethodTagTraitUseRuleTest.php b/tests/PHPStan/Rules/Classes/MethodTagTraitUseRuleTest.php
@@ -33,7 +33,7 @@ protected function getRule(): TRule
 					$container,
 				),
 				new GenericObjectTypeCheck(),
-				new MissingTypehintCheck(true, []),
+				new MissingTypehintCheck(true, [], true),
 				new UnresolvableTypeHelper(),
 				true,
 				true,
diff --git a/tests/PHPStan/Rules/Classes/MixinRuleTest.php b/tests/PHPStan/Rules/Classes/MixinRuleTest.php
@@ -33,7 +33,7 @@ protected function getRule(): Rule
 					$container,
 				),
 				new GenericObjectTypeCheck(),
-				new MissingTypehintCheck(true, []),
+				new MissingTypehintCheck(true, [], true),
 				new UnresolvableTypeHelper(),
 				true,
 				true,
@@ -69,6 +69,10 @@ public function testRule(): void
 				'PHPDoc tag @mixin contains generic class ReflectionClass but does not specify its types: T',
 				50,
 			],
+			[
+				'PHPDoc tag @mixin contains generic interface Iterator but does not specify its types: TKey, TValue',
+				50,
+			],
 			[
 				'PHPDoc tag @mixin contains unknown class MixinRule\UnknownestClass.',
 				50,
diff --git a/tests/PHPStan/Rules/Classes/MixinTraitRuleTest.php b/tests/PHPStan/Rules/Classes/MixinTraitRuleTest.php
@@ -32,7 +32,7 @@ protected function getRule(): Rule
 					$container,
 				),
 				new GenericObjectTypeCheck(),
-				new MissingTypehintCheck(true, []),
+				new MissingTypehintCheck(true, [], true),
 				new UnresolvableTypeHelper(),
 				true,
 				true,
diff --git a/tests/PHPStan/Rules/Classes/MixinTraitUseRuleTest.php b/tests/PHPStan/Rules/Classes/MixinTraitUseRuleTest.php
@@ -32,7 +32,7 @@ protected function getRule(): Rule
 					$container,
 				),
 				new GenericObjectTypeCheck(),
-				new MissingTypehintCheck(true, []),
+				new MissingTypehintCheck(true, [], true),
 				new UnresolvableTypeHelper(),
 				true,
 				true,
diff --git a/tests/PHPStan/Rules/Classes/PropertyTagRuleTest.php b/tests/PHPStan/Rules/Classes/PropertyTagRuleTest.php
@@ -32,7 +32,7 @@ protected function getRule(): TRule
 					$container,
 				),
 				new GenericObjectTypeCheck(),
-				new MissingTypehintCheck(true, []),
+				new MissingTypehintCheck(true, [], true),
 				new UnresolvableTypeHelper(),
 				true,
 				true,
diff --git a/tests/PHPStan/Rules/Classes/PropertyTagTraitRuleTest.php b/tests/PHPStan/Rules/Classes/PropertyTagTraitRuleTest.php
@@ -32,7 +32,7 @@ protected function getRule(): TRule
 					$container,
 				),
 				new GenericObjectTypeCheck(),
-				new MissingTypehintCheck(true, []),
+				new MissingTypehintCheck(true, [], true),
 				new UnresolvableTypeHelper(),
 				true,
 				true,
diff --git a/tests/PHPStan/Rules/Classes/PropertyTagTraitUseRuleTest.php b/tests/PHPStan/Rules/Classes/PropertyTagTraitUseRuleTest.php
@@ -32,7 +32,7 @@ protected function getRule(): TRule
 					$container,
 				),
 				new GenericObjectTypeCheck(),
-				new MissingTypehintCheck(true, []),
+				new MissingTypehintCheck(true, [], true),
 				new UnresolvableTypeHelper(),
 				true,
 				true,
diff --git a/tests/PHPStan/Rules/Constants/MissingClassConstantTypehintRuleTest.php b/tests/PHPStan/Rules/Constants/MissingClassConstantTypehintRuleTest.php
@@ -15,7 +15,7 @@ class MissingClassConstantTypehintRuleTest extends RuleTestCase
 
 	protected function getRule(): Rule
 	{
-		return new MissingClassConstantTypehintRule(new MissingTypehintCheck(true, []));
+		return new MissingClassConstantTypehintRule(new MissingTypehintCheck(true, [], true));
 	}
 
 	public function testRule(): void
diff --git a/tests/PHPStan/Rules/Functions/MissingFunctionParameterTypehintRuleTest.php b/tests/PHPStan/Rules/Functions/MissingFunctionParameterTypehintRuleTest.php
@@ -14,7 +14,7 @@ class MissingFunctionParameterTypehintRuleTest extends RuleTestCase
 
 	protected function getRule(): Rule
 	{
-		return new MissingFunctionParameterTypehintRule(new MissingTypehintCheck(true, []));
+		return new MissingFunctionParameterTypehintRule(new MissingTypehintCheck(true, [], true));
 	}
 
 	public function testRule(): void
diff --git a/tests/PHPStan/Rules/Functions/MissingFunctionReturnTypehintRuleTest.php b/tests/PHPStan/Rules/Functions/MissingFunctionReturnTypehintRuleTest.php
@@ -14,7 +14,7 @@ class MissingFunctionReturnTypehintRuleTest extends RuleTestCase
 
 	protected function getRule(): Rule
 	{
-		return new MissingFunctionReturnTypehintRule(new MissingTypehintCheck(true, []));
+		return new MissingFunctionReturnTypehintRule(new MissingTypehintCheck(true, [], true));
 	}
 
 	public function testRule(): void
@@ -58,6 +58,27 @@ public function testRule(): void
 				'Function MissingFunctionReturnTypehint\callableNestedNoPrototype() return type has no signature specified for callable.',
 				141,
 			],
+			[
+				'Function MissingFunctionReturnTypehint\returnsGeneratorOfIntegersNoPrototype() return type with generic class Generator does not specify its types: TKey, TValue, TSend, TReturn',
+				152,
+			],
+			[
+				'Function MissingFunctionReturnTypehint\returnsGeneratorOfIntegersByStringNoPrototype() return type with generic class Generator does not specify its types: TKey, TValue, TSend, TReturn',
+				169,
+			],
+			[
+				'Function MissingFunctionReturnTypehint\returnsIteratorNoPrototype() return type with generic interface Iterator does not specify its types: TKey, TValue',
+				186,
+			],
+			[
+				'Function MissingFunctionReturnTypehint\returnsIteratorAggregateNoPrototype() return type with generic interface IteratorAggregate does not specify its types: TKey, TValue',
+				199,
+			],
+			[
+				'Function MissingFunctionReturnTypehint\returnsTraversableNoPrototype() return type has no value type specified in iterable type Traversable.',
+				212,
+				MissingTypehintCheck::MISSING_ITERABLE_VALUE_TYPE_TIP,
+			],
 		]);
 	}
 
diff --git a/tests/PHPStan/Rules/Functions/data/missing-function-return-typehint.php b/tests/PHPStan/Rules/Functions/data/missing-function-return-typehint.php
@@ -148,4 +148,77 @@ function callableNestedNoPrototype() : callable{
 	function callableNestedWithPrototype() : callable{
 
 	}
+
+	function returnsGeneratorOfIntegersNoPrototype(): \Generator
+	{
+		yield 1;
+		yield 2;
+		yield 3;
+	}
+
+	/**
+	 * @return \Generator<int, int>
+	 */
+	function returnsGeneratorOfIntegersWithPrototype(): \Generator
+	{
+		yield 1;
+		yield 2;
+		yield 3;
+	}
+
+	function returnsGeneratorOfIntegersByStringNoPrototype(): \Generator
+	{
+		yield '1' => 1;
+		yield '2' => 2;
+		yield '3' => 3;
+	}
+
+	/**
+	 * @return \Generator<string, int>
+	 */
+	function returnsGeneratorOfIntegersByStringWithPrototype(): \Generator
+	{
+		yield '1' => 1;
+		yield '2' => 2;
+		yield '3' => 3;
+	}
+
+	function returnsIteratorNoPrototype(): \Iterator
+	{
+		yield 'test';
+	}
+
+	/**
+	 * @return \Iterator<array-key,string>
+	 */
+	function returnsIteratorWithPrototype(): \Iterator
+	{
+		yield 'test';
+	}
+
+	function returnsIteratorAggregateNoPrototype(): \IteratorAggregate
+	{
+		return new \ArrayObject([]);
+	}
+
+	/**
+	 * @return \IteratorAggregate<array-key,string>
+	 */
+	function returnsIteratorAggregateWithPrototype(): \IteratorAggregate
+	{
+		return new \ArrayObject([]);
+	}
+
+	function returnsTraversableNoPrototype(): \Traversable
+	{
+		yield 'test';
+	}
+
+	/**
+	 * @return \Traversable<array-key,string>
+	 */
+	function returnsTraversableWithPrototype(): \Traversable
+	{
+		yield 'test';
+	}
 }
diff --git a/tests/PHPStan/Rules/Methods/MissingMethodParameterTypehintRuleTest.php b/tests/PHPStan/Rules/Methods/MissingMethodParameterTypehintRuleTest.php
@@ -14,7 +14,7 @@ class MissingMethodParameterTypehintRuleTest extends RuleTestCase
 
 	protected function getRule(): Rule
 	{
-		return new MissingMethodParameterTypehintRule(new MissingTypehintCheck(true, []));
+		return new MissingMethodParameterTypehintRule(new MissingTypehintCheck(true, [], true));
 	}
 
 	public function testRule(): void
diff --git a/tests/PHPStan/Rules/Methods/MissingMethodReturnTypehintRuleTest.php b/tests/PHPStan/Rules/Methods/MissingMethodReturnTypehintRuleTest.php
@@ -15,7 +15,7 @@ class MissingMethodReturnTypehintRuleTest extends RuleTestCase
 
 	protected function getRule(): Rule
 	{
-		return new MissingMethodReturnTypehintRule(new MissingTypehintCheck(true, []));
+		return new MissingMethodReturnTypehintRule(new MissingTypehintCheck(true, [], true));
 	}
 
 	public function testRule(): void
@@ -54,6 +54,11 @@ public function testRule(): void
 				'Method MissingMethodReturnTypehint\CallableSignature::doFoo() return type has no signature specified for callable.',
 				99,
 			],
+			[
+				'Method MissingMethodReturnTypehint\IterableIntersection::doFoo() return type has no value type specified in iterable type Traversable.',
+				110,
+				MissingTypehintCheck::MISSING_ITERABLE_VALUE_TYPE_TIP,
+			],
 			[
 				'Method MissingMethodReturnTypehint\Baz::returnsGenericWithSomeDefaults() return type with generic class MissingMethodReturnTypehint\GenericClassWithSomeDefaults does not specify its types: T, U (1-2 required)',
 				142,
diff --git a/tests/PHPStan/Rules/Methods/MissingMethodSelfOutTypeRuleTest.php b/tests/PHPStan/Rules/Methods/MissingMethodSelfOutTypeRuleTest.php
@@ -14,7 +14,7 @@ class MissingMethodSelfOutTypeRuleTest extends RuleTestCase
 
 	protected function getRule(): TRule
 	{
-		return new MissingMethodSelfOutTypeRule(new MissingTypehintCheck(true, []));
+		return new MissingMethodSelfOutTypeRule(new MissingTypehintCheck(true, [], true));
 	}
 
 	public function testRule(): void
diff --git a/tests/PHPStan/Rules/Methods/data/missing-method-return-typehint.php b/tests/PHPStan/Rules/Methods/data/missing-method-return-typehint.php
@@ -106,7 +106,7 @@ public function doFoo(): callable
 class IterableIntersection
 {
 
-	/** @return FooInterface[]|\Traversable */
+	/** @return FooInterface[]&\Traversable<array-key, FooInterface> */
 	public function doFoo(): \Traversable
 	{
 
diff --git a/tests/PHPStan/Rules/PhpDoc/FunctionAssertRuleTest.php b/tests/PHPStan/Rules/PhpDoc/FunctionAssertRuleTest.php
@@ -29,7 +29,7 @@ protected function getRule(): Rule
 				$reflectionProvider,
 				$container,
 			),
-			new MissingTypehintCheck(true, []),
+			new MissingTypehintCheck(true, [], true),
 			new GenericObjectTypeCheck(),
 			true,
 			true,
diff --git a/tests/PHPStan/Rules/PhpDoc/InvalidPhpDocVarTagTypeRuleTest.php b/tests/PHPStan/Rules/PhpDoc/InvalidPhpDocVarTagTypeRuleTest.php
@@ -32,7 +32,7 @@ protected function getRule(): Rule
 				$container,
 			),
 			new GenericObjectTypeCheck(),
-			new MissingTypehintCheck(true, []),
+			new MissingTypehintCheck(true, [], true),
 			new UnresolvableTypeHelper(),
 			true,
 			true,
diff --git a/tests/PHPStan/Rules/PhpDoc/MethodAssertRuleTest.php b/tests/PHPStan/Rules/PhpDoc/MethodAssertRuleTest.php
diff --git a/tests/PHPStan/Rules/Properties/MissingPropertyTypehintRuleTest.php b/tests/PHPStan/Rules/Properties/MissingPropertyTypehintRuleTest.php
diff --git a/tests/PHPStan/Rules/Properties/SetPropertyHookParameterRuleTest.php b/tests/PHPStan/Rules/Properties/SetPropertyHookParameterRuleTest.php

Original file line number	Diff line number	Diff line change
`@@ -54,6 +54,8 @@ public function __construct(`
`54`	`54`	`private bool $checkMissingCallableSignature,`
`55`	`55`	`#[AutowiredParameter(ref: '%featureToggles.skipCheckGenericClasses%')]`
`56`	`56`	`private array $skipCheckGenericClasses,`
	`57`	`+ #[AutowiredParameter(ref: '%featureToggles.checkGenericIterableClasses%')]`
	`58`	`+ private bool $checkGenericIterableClasses,`
`57`	`59`	`)`
`58`	`60`	`{`
`59`	`61`	`}`
`@@ -118,7 +120,13 @@ public function getNonGenericObjectTypesWithGenericClass(Type $type): array`
`118`	`120`	`if ($classReflection === null) {`
`119`	`121`	`return $type;`
`120`	`122`	`}`
`121`		`- if (in_array($classReflection->getName(), self::ITERABLE_GENERIC_CLASS_NAMES, true)) {`
	`123`	`+ if (`
	`124`	`+ $classReflection->getName() === Traversable::class // already covered by getIterableTypesWithMissingValueTypehint`
	`125`	`+ \|\| (`
	`126`	`+ !$this->checkGenericIterableClasses &&`
	`127`	`+ in_array($classReflection->getName(), self::ITERABLE_GENERIC_CLASS_NAMES, true)`
	`128`	`+ )`
	`129`	`+ ) {`
`122`	`130`	`// checked by getIterableTypesWithMissingValueTypehint() already`
`123`	`131`	`return $type;`
`124`	`132`	`}`
Original file line number	Diff line number	Diff line change
`@@ -21,7 +21,7 @@ class PDOStatement implements Traversable, IteratorAggregate`
`21`	`21`	`public function getColumnMeta(int $column) {}`
`22`	`22`
`23`	`23`	`/**`
`24`		`- * @return Iterator`
	`24`	`+ * @return Iterator<mixed, array<int\|string, mixed>>`
`25`	`25`	`*/`
`26`	`26`	`public function getIterator() {}`
`27`	`27`	`}`
Original file line number	Diff line number	Diff line change
`@@ -22,6 +22,9 @@ public function isRepeated(): bool`
`22`	`22`	`{`
`23`	`23`	`}`
`24`	`24`
	`25`	`+ /**`
	`26`	`+ * @return array<array-key, mixed>`
	`27`	`+ */`
`25`	`28`	`public function getArguments(): array`
`26`	`29`	`{`
`27`	`30`	`}`
Original file line number	Diff line number	Diff line change
`@@ -9,5 +9,5 @@ function testPDOStatementGetIterator(): void {`
`9`	`9`	`$pdo = new PDO('sqlite::memory:');`
`10`	`10`	`$stmt = $pdo->query('SELECT 1');`
`11`	`11`
`12`		`- assertType('Iterator', $stmt->getIterator());`
	`12`	`+ assertType('Iterator<mixed, array<int\|string, mixed>>', $stmt->getIterator());`
`13`	`13`	`}`