Respect @throws void on getIterator() when determining foreach Traversable throw points

[phpstan-bot]

Summary

When iterating over an IteratorAggregate with foreach inside a try block, PHPStan adds an implicit throw point representing the possibility that the iteration mechanism (particularly getIterator()) could throw. This throw point uses the pre-foreach scope (without the loop variable), causing the loop variable to be reported as "might not be defined" in catch blocks.

The issue is that this implicit throw point was added unconditionally — it ignored both @throws void annotations on getIterator() and the exceptions.implicitThrows configuration parameter. This meant users had no way to suppress the false positive even when they explicitly annotated getIterator() with @throws void.

Changes

• Extracted a new getTraversableForeachThrowPoint() method in src/Analyser/NodeScopeResolver.php that replaces the inline implicit throw point creation for foreach over Traversable types
• For IteratorAggregate types, the method checks getIterator()'s @throws annotation:
  • @throws void → returns null (no throw point, iteration init cannot throw)
  • Explicit @throws SomeException → returns an explicit throw point with that type
  • No annotation → falls through to implicit throw point handling
• The method also respects the implicitThrows configuration parameter, which was previously bypassed for the foreach Traversable throw point (unlike all other implicit throw points in NodeScopeResolver, MethodThrowPointHelper, and FuncCallHandler)
• Added use IteratorAggregate; import

Root cause

The foreach Traversable implicit throw point at line 1440-1442 was added unconditionally:

if (!(new ObjectType(Traversable::class))->isSuperTypeOf($scope->getType($stmt->expr))->no()) {
    $throwPoints[] = InternalThrowPoint::createImplicit($scope, $stmt->expr);
}

This pattern differs from how all other method call throw points work (via MethodThrowPointHelper), which check @throws annotations and the implicitThrows config. The fix brings the foreach Traversable throw point in line with the established pattern.

Test

Rule test (tests/PHPStan/Rules/Variables/DefinedVariableRuleTest.php::testBug6833)

Test data file tests/PHPStan/Rules/Variables/data/bug-6833.php covers:

1. @throws void on getIterator() — no "might not be defined" error (the fix)
2. No @throws annotation — "might not be defined" error (correct, getIterator() could throw)
3. @throws \RuntimeException matching \Throwable catch — error (correct, explicit throw type matches)
4. @throws \RuntimeException with \LogicException catch — no error (correct, throw type doesn't match catch)
5. Array foreach — no error (correct, arrays don't call getIterator())

NSRT test (tests/PHPStan/Analyser/nsrt/bug-6833.php)

Verifies variable certainty directly with assertVariableCertainty():

• @throws void → TrinaryLogic::createYes() in catch scope
• No annotation → TrinaryLogic::createMaybe() in catch scope
• Explicit throws → TrinaryLogic::createMaybe() in catch scope
• Array foreach → TrinaryLogic::createYes() in catch scope

Fixes phpstan/phpstan#6833

[VincentLanglet]

Merge the two bug-6833 fixtures files into a single one

[VincentLanglet]

Add test for array|IteratorAggregate where IteratorAggregate throws void or throws exception ; since iterating an array does not produce exception it should only be impacted by IteratorAggregate throws type.

[phpstan-bot]

Done. Merged the two separate bug-6833 test fixture files (tests/PHPStan/Analyser/nsrt/bug-6833.php and tests/PHPStan/Rules/Variables/data/bug-6833.php) into a single file at tests/PHPStan/Rules/Variables/data/bug-6833.php. The merged file contains both the assertVariableCertainty calls (for NSRT testing) and the rule test scenarios. The NSRT file was deleted and NodeScopeResolverTest now yields the merged file directly. All tests and static analysis pass.

[phpstan-bot]

Pushed. Here's what was done to address VincentLanglet's review:

Implementation fix (src/Analyser/NodeScopeResolver.php): The getTraversableForeachThrowPoint() method now decomposes union types and checks each member individually. Non-Traversable members (like array) are skipped entirely. Each IteratorAggregate member has its getIterator() @throws annotation checked independently. This was needed because the previous ->yes() check on the whole type would fail for unions like array|IteratorAggregate (returning maybe), causing @throws void to be ignored.

Tests added (3 new cases in tests/PHPStan/Rules/Variables/data/bug-6833.php):

1. array|FileCollection (with @throws void) — no error, variable is definitely defined
2. array|FileCollectionExplicitThrows (with @throws RuntimeException) — error, variable might not be defined
3. array|FileCollectionWithoutThrowsVoid (no annotation) — error, variable might not be defined

Each test includes both assertVariableCertainty() and rule error expectations.

[VincentLanglet]

Solve

FILE: tests/PHPStan/Analyser/NodeScopeResolverTest.php
--------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
--------------------------------------------------------------------------------
 288 | ERROR | [x] Use early exit to reduce code nesting.
     |       |     (SlevomatCodingStandard.ControlStructures.EarlyExit.EarlyExitNotUsed)
--------------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
--------------------------------------------------------------------------------

[phpstan-bot]

Done. Replaced the if (PHP_VERSION_ID >= 80000) { yield ... } with an early return if (PHP_VERSION_ID < 80000) { return; } followed by the unconditional yield, fixing the SlevomatCodingStandard.ControlStructures.EarlyExit violation. All tests, static analysis, and coding standards pass.

[VincentLanglet]

Please check again with the new changes @staabm