Narrow foreach body to non-empty behind an opt-in toggle

Inside a foreach body the iterated expression is provably non-empty, so it
can be narrowed (list to non-empty-list, array to non-empty-array) at body
entry. Before, this happened only when polluteScopeWithAlwaysIterableForeach
was on, so with the flag off (as phpstan-strict-rules sets it) the narrowing
disappeared even though the body is only entered when the iteratee is
non-empty.

The narrowing is gated behind the new feature toggle narrowForeachBodyNonEmpty,
off by default. With it off the body scope is built exactly as before, so no
behaviour changes. With it on, the body narrows regardless of the flag. The
after-loop scope keeps that precision (a value variable can be seen as defined
where the iteratee is later proven non-empty), which is why the toggle is
opt-in and not enabled under bleedingEdge yet.

Closes phpstan/phpstan#13312

Amp-Thread-ID: https://ampcode.com/threads/T-01a19219-6260-7460-a52b-a418f709e4bf

Author: zonuexe

conf/config.neon

@@ -47,6 +47,7 @@ parameters:
 		rawMessageInBaseline: false
 		reportNestedTooWideType: false
 		assignToByRefForeachExpr: false
+		narrowForeachBodyNonEmpty: false
 		curlSetOptArrayTypes: false
 		magicDirInInclude: false
 		checkDateIntervalConstructor: false

conf/parametersSchema.neon

@@ -44,6 +44,7 @@ parametersSchema:
 		rawMessageInBaseline: bool()
 		reportNestedTooWideType: bool()
 		assignToByRefForeachExpr: bool()
+		narrowForeachBodyNonEmpty: bool()
 		curlSetOptArrayTypes: bool()
 		magicDirInInclude: bool()
 		checkDateIntervalConstructor: bool()

src/Analyser/StmtHandler/ForeachHandler.php

@@ -90,6 +90,8 @@ public function __construct(
 		private AssignHandler $assignHandler,
 		#[AutowiredParameter]
 		private bool $polluteScopeWithAlwaysIterableForeach,
+		#[AutowiredParameter(ref: '%featureToggles.narrowForeachBodyNonEmpty%')]
+		private bool $narrowForeachBodyNonEmpty,
 	)
 	{
 	}
@@ -156,9 +158,12 @@ public function processStmt(
 		// the "iteratee !== []" narrowing every loop pass merges in - composed
 		// once from the iteratee's result (the same sentinel comparison the
 		// walked synthetic would delegate to); the walk is the composition's
-		// miss seam
+		// miss seam. The loop body is only entered when the iteratee is
+		// non-empty; narrowForeachBodyNonEmpty narrows it there (list to
+		// non-empty-list, array to non-empty-array) even with
+		// polluteScopeWithAlwaysIterableForeach off.
 		$nonEmptyIterateeScope = $scope;
-		if ($this->polluteScopeWithAlwaysIterableForeach) {
+		if ($this->narrowForeachBodyNonEmpty || $this->polluteScopeWithAlwaysIterableForeach) {
 			$identicalNarrowingHelper = $this->container->getByType(IdenticalNarrowingHelper::class);
 			$emptyArrayType = new ConstantArrayType([], []);
 			$nonEmptyTypes = $identicalNarrowingHelper->specifyIdenticalAgainstType(

tests/PHPStan/Analyser/Bug13312NoPolluteTest.php

@@ -0,0 +1,36 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Analyser;
+
+use PHPStan\Testing\TypeInferenceTestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+class Bug13312NoPolluteTest extends TypeInferenceTestCase
+{
+
+	public static function dataFileAsserts(): iterable
+	{
+		yield from self::gatherAssertTypes(__DIR__ . '/data/bug-13312-no-pollute.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__ . '/bug-13312-no-pollute.neon',
+		];
+	}
+
+}

tests/PHPStan/Analyser/Bug13312StableTest.php

@@ -0,0 +1,36 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Analyser;
+
+use PHPStan\Testing\TypeInferenceTestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+class Bug13312StableTest extends TypeInferenceTestCase
+{
+
+	public static function dataFileAsserts(): iterable
+	{
+		yield from self::gatherAssertTypes(__DIR__ . '/data/bug-13312-stable.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__ . '/bug-13312-stable.neon',
+		];
+	}
+
+}

tests/PHPStan/Analyser/bug-13312-no-pollute.neon

@@ -0,0 +1,4 @@
+parameters:
+	polluteScopeWithAlwaysIterableForeach: false
+	featureToggles:
+		narrowForeachBodyNonEmpty: true

tests/PHPStan/Analyser/bug-13312-stable.neon

@@ -0,0 +1,2 @@
+parameters:
+	polluteScopeWithAlwaysIterableForeach: false

tests/PHPStan/Analyser/data/bug-13312-no-pollute.php

@@ -0,0 +1,37 @@
+<?php declare(strict_types = 1);
+
+namespace Bug13312NoPollute;
+
+use function PHPStan\Testing\assertType;
+
+/** @param list<mixed> $arr */
+function foo(array $arr): void {
+	assertType('list<mixed>', $arr);
+	foreach ($arr as $v) {
+		assertType('non-empty-list<mixed>', $arr);
+	}
+	assertType('list<mixed>', $arr);
+
+	for ($i = 0; $i < count($arr); ++$i) {
+		assertType('non-empty-list<mixed>', $arr);
+	}
+	assertType('list<mixed>', $arr);
+}
+
+/** @param array<string, int> $arr */
+function fooStringKeyed(array $arr): void {
+	assertType('array<string, int>', $arr);
+	foreach ($arr as $v) {
+		assertType('non-empty-array<string, int>', $arr);
+	}
+	assertType('array<string, int>', $arr);
+}
+
+/** @param list<mixed> $arr */
+function fooReassign(array $arr): void {
+	foreach ($arr as $v) {
+		$arr = [];
+		assertType('array{}', $arr);
+	}
+	assertType('array{}', $arr);
+}

tests/PHPStan/Analyser/data/bug-13312-stable.php

@@ -0,0 +1,32 @@
+<?php declare(strict_types = 1);
+
+namespace Bug13312Stable;
+
+use function PHPStan\Testing\assertType;
+
+// With polluteScopeWithAlwaysIterableForeach off and narrowForeachBodyNonEmpty off
+// (the stable default), the foreach body does not narrow the iterated expression.
+// The for-loop narrowing is a separate mechanism and still applies.
+
+/** @param list<mixed> $arr */
+function foo(array $arr): void {
+	assertType('list<mixed>', $arr);
+	foreach ($arr as $v) {
+		assertType('list<mixed>', $arr);
+	}
+	assertType('list<mixed>', $arr);
+
+	for ($i = 0; $i < count($arr); ++$i) {
+		assertType('non-empty-list<mixed>', $arr);
+	}
+	assertType('list<mixed>', $arr);
+}
+
+/** @param array<string, int> $arr */
+function fooStringKeyed(array $arr): void {
+	assertType('array<string, int>', $arr);
+	foreach ($arr as $v) {
+		assertType('array<string, int>', $arr);
+	}
+	assertType('array<string, int>', $arr);
+}

tests/PHPStan/Analyser/nsrt/bug-13312.php

@@ -32,6 +32,24 @@ function foo(array $arr): void {
 }
 
 
+/** @param array<string, int> $arr */
+function fooStringKeyed(array $arr): void {
+	assertType('array<string, int>', $arr);
+	foreach ($arr as $v) {
+		assertType('non-empty-array<string, int>', $arr);
+	}
+	assertType('array<string, int>', $arr);
+}
+
+/** @param list<mixed> $arr */
+function fooReassign(array $arr): void {
+	foreach ($arr as $v) {
+		$arr = [];
+		assertType('array{}', $arr);
+	}
+	assertType('array{}', $arr);
+}
+
 function fooBar(mixed $mixed): void {
 	assertType('mixed', $mixed);
 	foreach ($mixed as $v) {