Language: foreach over Traversable / Iterator objects (Zend parity)

[PurHur]

Category

language / runtime

Problem

foreach ($obj as $k => $v) only supports arrays and generators today. Objects implementing Iterator, IteratorAggregate, or Traversable fatals on VM:

LogicException: Iterator reset requires an array

Zend walks objects via internal iterator handlers (zend_iterator_*).

php-src reference

• Zend/zend_interfaces.c — zend_class_implements, Traversable / Iterator checks
• Zend/zend_execute.c — ZEND_FE_RESET_R, ZEND_FE_FETCH_R, object iterator path
• Zend/zend_iterators.c — zend_iterator_* helpers for user iterators

Repro (today)

<?php
class T implements Iterator {
    private int $i = 0;
    public function current(): mixed { return $this->i; }
    public function key(): mixed { return $this->i; }
    public function next(): void { $this->i++; }
    public function rewind(): void { $this->i = 0; }
    public function valid(): bool { return $this->i < 3; }
}
foreach (new T() as $k => $v) {
    echo "$k:$v\n";
}

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/vm.php repro.php'

Zend PHP: prints 0:0, 1:1, 2:2
This compiler: LogicException: Iterator reset requires an array at lib/VM.php:1126

Also cover IteratorAggregate (getIterator(): Traversable).

Scope (this repo)

Layer	Files	Notes
Compiler	lib/Compiler.php	Emit object-foreach ops or reuse iterator opcodes with object dispatch
VM	lib/VM.php	TYPE_ITER_RESET / TYPE_ITER_VALID / TYPE_ITER_FETCH call $obj->rewind() / valid() / current() / key() / next()
JIT	lib/JIT.php	Phase 2 — VM fallback acceptable v1
Tests	test/compliance/cases/foreach_iterator.phpt, foreach_iterator_aggregate.phpt	VM first

Done when

• Repro prints three lines on VM (Iterator + IteratorAggregate fixtures)
• Non-iterable object throws TypeError (or Zend-equivalent) — not LogicException
• ./script/ci-fast.sh --filter foreach_iterator green
• docs/capabilities-syntax.md documents object foreach (regenerate via script/capability-syntax.php)

Verification

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter foreach_iterator'

Dependencies

• Language: Generators (yield and yield from) #167 generators (separate opcode path — do not conflate)
• Language: Magic methods (__get, __set, __call, __toString) #146 magic methods (optional for Iterator user classes with __get)

Links

• Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492 self-host (compiler uses foreach over arrays extensively; object foreach unblocks SPL-style helpers)
• 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 ROADMAP Phase 2 language

[PurHur]

claim: worker-lane-a — starting this run

[PurHur]

claim: cursor-agent-lane-a — rebasing PR #3245 onto current master (conflict fix + verification)