Implement bidirectional array type narrowing in foreach loops

[takeokunn]

Summary

Closes phpstan/phpstan#13959

When a foreach value variable is narrowed via instanceof, the source array's item type is now also narrowed accordingly.

Example

/** @param list<Animal|string> $animals */
function example(array $animals): void {
    foreach ($animals as $animal) {
        if ($animal instanceof Dog) {
            // $animals is now list<Dog>
        }
    }
}

Implementation

• Add ForeachSourceTracking class to track foreach value → array relationships
• Add narrowItemType() method to Type interface (47 implementations)
• Extend TypeSpecifier with foreach narrowing propagation logic
• Preserve list markers (list stays list, not array<int, T>)

Limitations

• Only narrows on instanceof checks (conservative approach)
• Variable array offsets do not trigger narrowing
• By-reference foreach does not narrow (mutation safety)

Commits

#	Hash	Message
1	853982d	Type narrowing: Implement bidirectional array type narrowing (#13959)
2	b2ff927	Refactor: Optimize and document foreach type narrowing implementation

[thg2k]

/** @param list<Animal|string> $animals */
function example(array $animals): void {
    foreach ($animals as $animal) {
        if ($animal instanceof Dog) {
            // $animals is now list<Dog>
        }
    }
}

I do not understand how $animals is list<Dog> in your example. I only see
that one specific item in the array Dog, but how does that imply that all
the elements are?

Maybe you meant something like the following?

/** @param list<Animal|string> $animals */
function example(array $animals): void {
    foreach ($animals as $animal) {
        if (!$animal instanceof Dog)
            throw \Exception("not Dog");
    }
    // $animals is now list<Dog>
}