Widen only the variables a loop can write when its scope converges

[ondrejmirtes]

Closes phpstan/phpstan#12666

When a loop's scope converges, MutatingScope::generalizeWith() widened every variable whose type differed between two passes. A variable the loop never writes differs only through narrowing by the loop's condition. In while ($xi < $xn) { $xi += 0.1; } the first pass narrows $xn to int<2, max>, the next pass cannot once $xi is a float, and generalizing the two turned int<1, max> into int.

Such a variable enters every iteration with its value from before the loop, so the convergence passes of while, do-while, for and foreach loops now union its types instead of generalizing them. LoopWrittenVariableNames collects the variables a loop can write:

• From the loop's AST: assignments, increments, destructuring, foreach bindings, catch, static, global, unset and by-reference closure uses, cached on the loop node. Variable variables, extract(), parse_str(), eval and include make the set unknown, and every variable is widened as before.
• From the variable flow of the convergence pass (Report values assigned to variables that are never read #6330, Report variable writes whose value never reaches a use, per array offset #6334), because whether an argument is passed by reference is known only from the callee's reflection. Treating every argument as a write would undo the fix as soon as the variable is passed to any call inside the loop.
• From references created before the loop, read off the scope in generalizeWith(). $ref = &$xn; followed by $ref = $xn + 1; inside the loop still widens $xn.

The goto and closure by-reference fixpoints and the post-loop generalization in ForHandler are unchanged. The PR targets 2.3.x because the variable flow it reads exists only there.

Tests

• nsrt/bug-12666.php is the sample from the issue.
• nsrt/loop-generalize-written-variables.php covers do-while, for, foreach, a constant array with unsealed keys and a variable passed by value inside the loop. It also covers the writes that must still widen: an increment, destructuring, a write through a reference, and array_push() in the body and in a for update.

Both files fail without the fix. The variants file also fails when the by-reference names from the flow are dropped, and when the reference scan is dropped.

Verification

• Full suite after rebasing onto Build a loop's back edge from its continue statements when the body end is unreachable #6420: 21809 tests, 97395 assertions, OK.
• make phpstan: no errors.
• phpcs and lint on the changed files: clean.
• Not measured: the three-project PHAR benchmark. The added work runs only on convergence passes that generalize: one cached AST walk per loop and one walk over the pass's variable flow.

🤖 Generated with Claude Code

https://claude.ai/code/session_014LVEGd9G9w8j64EZQ7rysC

[phpstan-bot]

You've opened the pull request against the latest branch 2.3.x. PHPStan 2.3 is not going to be released for months. If your code is relevant on 2.2.x and you want it to be released sooner, please rebase your pull request and change its target to 2.2.x.