必须显式实现Iterator或IteratorAggregate接口，否则foreach会报Fatal error；前者需完整实现current、key、next、rewind、valid五个方法，后者只需getIterator()返回合法迭代器实例。
想让自定义 PHP 类支持 foreach，必须显式实现迭代契约——不是加个魔术方法就能糊弄过去，少一个接口方法就会直接报 Fatal error: Class X must implement interface Iterator。
为什么直接 foreach 对象会报错
PHP 不会自动把普通对象变成可迭代结构。哪怕你只漏了 valid() 或把 rewind() 写成空函数，foreach 都会拒绝执行并抛出致命错误。这不是兼容性问题，是类型系统在强制你声明「我确实知道怎么走完这一趟」。
-
foreach不看__get()、__isset()，也不管属性是不是public - 它只认两个接口：
Iterator（全手动控制）或IteratorAggregate（委托给现成迭代器） - 错误信息常见两种：
Cannot use object as array（没实现任何迭代接口），或更明确的Object of class X could not be converted to string（内部尝试转字符串失败，本质还是迭代失败）
Iterator 接口五个方法怎么写才不崩
手写 Iterator 看似简单，但每个方法都有隐含约束。最容易翻车的是指针越界和状态不同步。
-
rewind()必须真正重置索引变量，比如$this->position = 0；只调用reset($this->data)不够，因为current()和key()可能不依赖数组内部指针 -
valid()别用isset($this->data[$this->position])——如果数组键不连续（比如[0 => 'a', 2 => 'c']），$this->position === 1时会误判为无效 - 推荐写法：
return $this->position >= 0 && $this->position data); -
current()必须返回当前有效元素，不能返回null或未定义值；PHP 8+ 建议加返回类型声明，如public function current(): mixed -
next()调用后，valid()应立刻反映新位置状态；建议在next()末尾加校验：if ($this->position >= count($this->data)) { $this->position = count($this->data); }
IteratorAggregate 比手写更安全的场景
如果你的类只是封装了一个数组（比如 $this->items），根本没必要自己实现五条逻辑——既容易错，又难维护。
立即学习“PHP免费学习笔记（深入）”；
- 只需实现
IteratorAggregate接口 +getIterator()方法 -
getIterator()必须返回一个迭代器对象，例如：return new ArrayIterator($this->items); - 常见错误：写成
return $this->items;——这返回的是数组，不是迭代器，foreach会直接报错 - 优势明显：自动继承
ArrayIterator的健壮性（包括键连续性处理、offsetExists支持等），且能无缝配合RecursiveArrayIterator处理嵌套
foreach 中修改集合导致迭代失效的坑
在 foreach 循环体里增删 $this->items 元素，几乎必然导致跳过元素、无限循环或 undefined offset 错误——因为迭代器状态和底层数据已脱节。
- PHP 的 SPL 迭代器不承诺「结构变更时的稳定性」，这是设计使然，不是 bug
- 正确做法：先用
array_keys()或收集要操作的$ids，循环结束后统一处理 - 若必须边遍历边改，放弃
foreach，改用传统for ($i = 0; $i items); $i++)，靠整数索引访问，绕过迭代器状态 - 性能敏感时，
Generator函数比手写Iterator更轻量，且天然规避状态管理问题
真正麻烦的从来不是写完五个方法，而是确保它们在各种边界条件下（空数组、键不连续、多次遍历、中途修改）都保持一致行为。多数时候，IteratorAggregate + ArrayIterator 就是那个被低估的稳解。
