Narrow foreach body to non-empty regardless of polluteScopeWithAlwaysIterableForeach by zonuexe · Pull Request #6094 · phpstan/phpstan-src

zonuexe · 2026-07-23T11:26:15Z

/** @param list<mixed> $arr */
function foo(array $arr): void {
	foreach ($arr as $v) {
		bar($arr);
	}
}

/** @param non-empty-list<mixed> $arr */
function bar(array $arr): void {}

This reproduces with polluteScopeWithAlwaysIterableForeach: false, which phpstan-strict-rules sets.

Inside the loop body $arr is provably non-empty. PHPStan already narrowed it there, but only as a side effect of polluteScopeWithAlwaysIterableForeach: with the flag off the in-body narrowing disappeared. A previous fix (phpstan-src#4162) added a test for it, but only under the default flag value, so the reported case kept failing under phpstan-strict-rules and the issue was reopened.

Opt-in toggle

The narrowing is gated behind a new feature toggle narrowForeachBodyNonEmpty, off by default.

off (default): the body scope is built exactly as before, no behaviour change.
on: the foreach body narrows the iterated expression regardless of the flag, so #13312 is fixed.

Narrowing the body also feeds the loop-exit scope, which with the flag off should stay conservative (it must not conclude the loop always iterated). After the body pass the iterated expression's possibly-empty-ness is restored in the after-loop scope, keeping any element types the body refined. This containment is partial: definedness that flows through variables the body builds, rather than through the iterated expression itself, still reaches the after-loop scope.

Because of that residual leak, the toggle is not enabled under bleedingEdge yet and stays opt-in until it is fully contained. That also keeps the change out of self-analysis, so no unrelated source needs touching.

Bug13312NoPolluteTest covers the toggle on; Bug13312StableTest covers the default (off), where the foreach body is left as-is.

phpstan-bot · 2026-07-25T14:33:22Z

This pull request has been marked as ready for review.

staabm · 2026-07-25T16:26:58Z

 		if ($commonReasons !== null && count($commonReasons) > 0) {
 			$decorated = [];
-			foreach (array_keys($innerAccepts) as $i) {
+			foreach (array_keys($innerAccepts) as $innerAcceptsIndex) {


I think we have the same problem here.. this change got necessary because the PR broke polluteScopeWithAlwaysIterableForeach?

You're right, and my earlier reply was wrong. Sorry. I checked: $i in UnionType::accepts() becomes defined after the first loop only because of this change, and it matches what polluteScopeWithAlwaysIterableForeach: true already produces. So it is the same leak, not a flag-independent fact.

The leak flows through conditionals between variables the loop body builds (here $innerAccepts), not through the iterated expression itself, and I could not strip it without also dropping non-emptiness that other code legitimately relies on. So instead of chasing full containment, I've gated the whole behaviour behind a bleedingEdge toggle, narrowForeachBodyNonEmpty.

With bleedingEdge off (stable), polluteScopeWithAlwaysIterableForeach: false behaves exactly as before: no in-body narrowing, no after-loop change. With bleedingEdge on, the body narrows and #13312 is fixed. This rename and the ConstantArrayType guards are only needed because the self-analysis config runs with bleedingEdge on.

please remove unrelated changes in

src/Type/UnionType.php

src/Type/Constant/ConstantArrayType.php

Done. I dropped both files. The toggle is no longer enabled under bleedingEdge, so the self-analysis config never turns it on and those source changes are not needed. It is opt-in only until the after-loop leak is fully contained.

The toggle is no longer enabled under bleedingEdge, so the self-analysis config never turns it on and those source changes are not needed. It is opt-in only until the after-loop leak is fully contained.

I think this indicates that this PR is still breaking polluteScopeWithAlwaysIterableForeach: false?

staabm · 2026-07-25T19:05:01Z

+	polluteScopeWithAlwaysIterableForeach: false
+	featureToggles:
+		narrowForeachBodyNonEmpty: true


do we need more tests with other combinations of this toggles?

Added Bug13312StableTest for the toggle-off case (foreach body left as list<mixed>, while the separate for-loop narrowing still applies). Bug13312NoPolluteTest covers toggle-on. Happy to add pollute-on combinations too if you want them.

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. Narrowing the body also feeds the loop-exit scope, which with the flag off must stay conservative: it must not conclude the loop always iterated. After the body pass the iterated expression's possibly-empty-ness is restored in the after-loop scope, keeping any element types the body refined. This containment is partial: definedness that flows through variables the body builds (rather than through the iterated expression itself) still reaches the after-loop scope. Because of that residual, the toggle is not enabled under bleedingEdge yet; it is opt-in until the leak is fully contained. Closes phpstan/phpstan#13312

zonuexe force-pushed the foreach-non-empty-narrowing branch 2 times, most recently from 568511a to 8aa4092 Compare July 23, 2026 13:07