PHP: полный мануал с примерами, функциями и ООП

<?php
$normal = new SplQueue();
$normal->enqueue('Ежедневный отчёт');
$normal->enqueue('Обновить каталог');

$urgent = new SplPriorityQueue();
$urgent->insert('Сбросить пароль', 100);
$urgent->insert('Проверить остаток', 20);

echo 'Срочно: ', $urgent->extract(), "\n";
echo 'По очереди: ', $normal->dequeue(), "\n";
echo 'Следом: ', $normal->dequeue(), "\n";

Срочно: Сбросить пароль
По очереди: Ежедневный отчёт
Следом: Обновить каталог

SplQueue выбирает первый добавленный элемент. SplPriorityQueue выбирает наибольший priority независимо от времени вставки. Это два разных требования, поэтому структуры не заменяют друг друга. Обе живут только в памяти процесса и не являются сервером фоновых заданий.

<?php
$week = new SplFixedArray(2);
$week[0] = 'Пн: 8 заказов';
$week[1] = 'Вт: 11 заказов';

$settings = new ArrayObject(['currency' => 'RUB']);
$order = (object) ['id' => 42];
$states = new SplObjectStorage();
$states[$order] = 'paid';

echo $week[1], "\n";
echo 'Валюта: ', $settings['currency'], "\n";
echo 'Заказ ', $order->id, ': ', $states[$order], "\n";

Вт: 11 заказов
Валюта: RUB
Заказ 42: paid

SplFixedArray выражает известное число позиций 0…n−1. ArrayObject оборачивает обычные ключи/значения объектным API. SplObjectStorage использует конкретный объект как ключ. Выбор идёт от требуемой операции, а не от слова «быстрее».

<?php
declare(strict_types=1);

$jobs = new SplQueue();
$jobs->enqueue('Импорт');
$jobs->enqueue('Отчёт');
$job = $jobs->dequeue();
echo 'Выполняем: ', $job, "\n";
echo 'Следующее: ', $jobs->bottom(), "\n";

Выполняем: Импорт
Следующее: Отчёт

После двух enqueue очередь содержит Импорт → Отчёт. dequeue удаляет Импорт и возвращает эту строку в присваивание $job. bottom читает оставшийся Отчёт без удаления. Ни один метод здесь сам не выполняет задание: полезное действие обозначено выводом.

<?php
declare(strict_types=1);

$jobs = new SplQueue();
$jobs->enqueue(['file' => 'orders.csv', 'rows' => 3]);
$jobs->enqueue(['file' => 'returns.csv', 'rows' => 1]);
while (!$jobs->isEmpty()) {
    $job = $jobs->dequeue();
    echo $job['file'], ': подготовлено строк ', $job['rows'], "\n";
}
echo 'Осталось заданий: ', $jobs->count(), "\n";

orders.csv: подготовлено строк 3
returns.csv: подготовлено строк 1
Осталось заданий: 0

Каждое задание теперь массив с именем и числом строк. ! превращает «пуста» в «не пуста»; while повторяет тело, пока это условие истинно. dequeue передаёт ровно один массив в $job и уменьшает очередь. После двух проходов условие ложно, выполняется последний echo. Файлы здесь описаны данными, их чтение не заявляется.

<?php
declare(strict_types=1);

$links = ['Главная' => ['Каталог', 'Контакты'], 'Каталог' => ['Главная', 'Чай'], 'Контакты' => [], 'Чай' => []];
$pending = new SplQueue();
$pending->enqueue('Главная');
$scheduled = ['Главная' => true];
while (!$pending->isEmpty()) {
    $page = $pending->dequeue();
    echo 'Раздел: ', $page, "\n";
    foreach ($links[$page] as $next) {
        if (!isset($scheduled[$next])) {
            $scheduled[$next] = true;
            $pending->enqueue($next);
        }
    }
}

Раздел: Главная
Раздел: Каталог
Раздел: Контакты
Раздел: Чай

Это конечный граф разделов, уже известный в памяти. foreach получает соседей текущей страницы. isset проверяет отметку; её ставят при постановке в очередь, поэтому две страницы не поставят один раздел дважды. Обратная ссылка Каталог → Главная не зацикливает обработку. Для загружаемого извне графа отдельно нужны пределы страниц, глубины и времени.

<?php
declare(strict_types=1);

$history = new SplStack();
$price = 500;
$history->push($price);
$price = 450;
$history->push($price);
$price = 400;
$price = $history->pop();
echo 'После отмены: ', $price, "\n";
$price = $history->pop();
echo 'После второй отмены: ', $price, "\n";

После отмены: 450
После второй отмены: 500

Перед изменением сохраняется старая цена. В стек последовательно попали 500 и 450; pop возвращает последнюю — 450 — в присваивание $price. Второй pop возвращает 500. Стек содержит числа, а не команды и не резервную копию базы; отмену связанных изменений нужно проектировать отдельно.

<?php
declare(strict_types=1);

$history = new SplStack();
$history->push('Создан черновик');
$history->push('Изменён заголовок');
foreach ($history as $step) {
    echo 'История: ', $step, "\n";
}
echo 'Отменяем: ', $history->pop(), "\n";
echo 'Остаётся: ', $history->top(), "\n";

История: Изменён заголовок
История: Создан черновик
Отменяем: Изменён заголовок
Остаётся: Создан черновик

SplStack фиксирует LIFO — «последний пришёл, первый вышел». foreach в режиме KEEP не уничтожает историю; затем pop действительно удаляет последнюю запись. top только читает оставшуюся. Надпись «Отменяем» показывает выбранную запись, а не автоматическое изменение документа.

<?php
declare(strict_types=1);

$route = new SplDoublyLinkedList();
$route->push('Склад');
$route->push('Магазин');
$route->unshift('Гараж');
foreach ($route as $index => $stop) {
    echo $index, ': ', $stop, "\n";
}

0: Гараж
1: Склад
2: Магазин

push добавил Склад и Магазин в конец, unshift — Гараж в начало. foreach передаёт текущий номер в $index, строку в $stop; => связывает две переменные обхода. Это позиции в текущем списке, не постоянные ID адресов.

<?php
declare(strict_types=1);

$times = new SplMinHeap();
$times->insert(30);
$times->insert(10);
$times->insert(20);
echo 'Ближайшая минута: ', $times->top(), "\n";
$minute = $times->extract();
echo 'Запланировано на минуту: ', $minute, "\n";
echo 'Следующая минута: ', $times->top(), "\n";

Ближайшая минута: 10
Запланировано на минуту: 10
Следующая минута: 20

insert передал три целых числа в кучу. SplMinHeap держит на вершине наименьшее — 10. top читает его без удаления. extract удаляет вершину и возвращает 10 в $minute; затем наверху 20. Числа — условные минуты от начала расписания, не текущие часы и не автоматический таймер.

<?php
declare(strict_types=1);

class DeadlineHeap extends SplHeap {
    protected function compare(mixed $first, mixed $second): int {
        return $second['day'] <=> $first['day'];
    }
}
$tasks = new DeadlineHeap();
$tasks->insert(['title' => 'Отчёт', 'day' => 18]);
$tasks->insert(['title' => 'Счёт', 'day' => 15]);
while (!$tasks->isEmpty()) {
    $task = $tasks->extract();
    echo $task['day'], ': ', $task['title'], "\n";
}

15: Счёт
18: Отчёт

class объявляет новый класс, extends наследует механизм SplHeap. protected compare вызывается самой кучей при insert/extract. При сравнении записи day=15 с day=18 параметры $first/$second получают эти записи; 18 <=> 15 возвращает положительное число, значит первая запись поднимается выше. return передаёт знак встроенному алгоритму, а не печатает запись. Позже extract возвращает всю запись в $task. Для равных сроков порядок здесь не обещан.

<?php
declare(strict_types=1);

$sizes = new SplMaxHeap();
foreach ([12, 40, 25] as $size) { $sizes->insert($size); }
$preview = clone $sizes;
foreach ($preview as $size) { echo 'Предпросмотр: ', $size, "\n"; }
echo 'Осталось в копии: ', $preview->count(), "\n";
echo 'В исходной куче: ', $sizes->count(), "\n";
echo 'Реально выбран: ', $sizes->extract(), "\n";

Предпросмотр: 40
Предпросмотр: 25
Предпросмотр: 12
Осталось в копии: 0
В исходной куче: 3
Реально выбран: 40

foreach кучи последовательно удаляет вершины. clone создаёт отдельный контейнер, поэтому обзор опустошает $preview, а не $sizes. Клонирование контейнера поверхностное: вложенные объекты остаются общими, поэтому это не снимок состояния всего графа объектов.

<?php
declare(strict_types=1);

$times = new SplMinHeap();
$times->insert(30);
$times->insert(10);
$times->insert(20);
echo 'Ближайшая минута: ', $times->top(), "\n";
$minute = $times->extract();
echo 'Запланировано на минуту: ', $minute, "\n";
echo 'Следующая минута: ', $times->top(), "\n";

Ближайшая минута: 10
Запланировано на минуту: 10
Следующая минута: 20

insert передал три целых числа в кучу. SplMinHeap держит на вершине наименьшее — 10. top читает его без удаления. extract удаляет вершину и возвращает 10 в $minute; затем наверху 20. Числа — условные минуты от начала расписания, не текущие часы и не автоматический таймер.

<?php
declare(strict_types=1);

$sizes = new SplMaxHeap();
foreach ([12, 40, 25] as $size) { $sizes->insert($size); }
$preview = clone $sizes;
foreach ($preview as $size) { echo 'Предпросмотр: ', $size, "\n"; }
echo 'Осталось в копии: ', $preview->count(), "\n";
echo 'В исходной куче: ', $sizes->count(), "\n";
echo 'Реально выбран: ', $sizes->extract(), "\n";

Предпросмотр: 40
Предпросмотр: 25
Предпросмотр: 12
Осталось в копии: 0
В исходной куче: 3
Реально выбран: 40

foreach кучи последовательно удаляет вершины. clone создаёт отдельный контейнер, поэтому обзор опустошает $preview, а не $sizes. Клонирование контейнера поверхностное: вложенные объекты остаются общими, поэтому это не снимок состояния всего графа объектов.

<?php
declare(strict_types=1);

$stock = new SplMaxHeap();
$stock->insert(12);
$stock->insert(40);
$stock->insert(25);
$amount = $stock->extract();
echo 'Первый объём: ', $amount, "\n";
echo 'Следующий объём: ', $stock->top(), "\n";

Первый объём: 40
Следующий объём: 25

SplMaxHeap выбирает наибольшее значение. extract возвращает 40, следующий top — 25. Мы храним только количества: если нужен ещё и артикул, используйте запись и собственное сравнение либо SplPriorityQueue с количеством как приоритетом.

<?php
declare(strict_types=1);

$sizes = new SplMaxHeap();
foreach ([12, 40, 25] as $size) { $sizes->insert($size); }
$preview = clone $sizes;
foreach ($preview as $size) { echo 'Предпросмотр: ', $size, "\n"; }
echo 'Осталось в копии: ', $preview->count(), "\n";
echo 'В исходной куче: ', $sizes->count(), "\n";
echo 'Реально выбран: ', $sizes->extract(), "\n";

Предпросмотр: 40
Предпросмотр: 25
Предпросмотр: 12
Осталось в копии: 0
В исходной куче: 3
Реально выбран: 40

foreach кучи последовательно удаляет вершины. clone создаёт отдельный контейнер, поэтому обзор опустошает $preview, а не $sizes. Клонирование контейнера поверхностное: вложенные объекты остаются общими, поэтому это не снимок состояния всего графа объектов.

<?php
declare(strict_types=1);

$jobs = new SplPriorityQueue();
$jobs->insert('Отчёт', 10);
$jobs->insert('Сброс пароля', 50);
echo 'Следующее: ', $jobs->top(), "\n";
$job = $jobs->extract();
echo 'Обработать: ', $job, "\n";
echo 'После него: ', $jobs->extract(), "\n";

Следующее: Сброс пароля
Обработать: Сброс пароля
После него: Отчёт

Первый аргумент insert — полезные данные, второй — приоритет. Большее число 50 важнее 10, поэтому «Сброс пароля» возвращается раньше. top не удаляет, extract удаляет. По умолчанию возвращаются данные; код лишь показывает выбранные задания и не отправляет письма.

<?php
declare(strict_types=1);

$jobs = new SplPriorityQueue();
$jobs->insert('Сброс пароля', 50);
$saved = $jobs->getExtractFlags();
$jobs->setExtractFlags(SplPriorityQueue::EXTR_PRIORITY);
echo 'Приоритет: ', $jobs->top(), "\n";
$jobs->setExtractFlags(SplPriorityQueue::EXTR_BOTH);
$entry = $jobs->current();
echo $entry['data'], ': ', $entry['priority'], "\n";
$jobs->setExtractFlags($saved);
echo 'К исполнению: ', $jobs->extract(), "\n";

Приоритет: 50
Сброс пароля: 50
К исполнению: Сброс пароля

EXTR_PRIORITY меняет форму чтения на число; EXTR_BOTH возвращает массив с ключами data и priority. Это не меняет очередность. getExtractFlags сохранил прежнюю настройку EXTR_DATA, setExtractFlags восстановил её, поэтому extract снова вернул строку задания.

<?php
declare(strict_types=1);

class StableJobs extends SplPriorityQueue {
    public function compare(mixed $first, mixed $second): int {
        $urgency = $first['level'] <=> $second['level'];
        if ($urgency !== 0) { return $urgency; }
        return $second['sequence'] <=> $first['sequence'];
    }
}
$jobs = new StableJobs();
$jobs->insert('Отчёт A', ['level' => 10, 'sequence' => 1]);
$jobs->insert('Отчёт B', ['level' => 10, 'sequence' => 2]);
$jobs->insert('Пароль', ['level' => 50, 'sequence' => 3]);
while (!$jobs->isEmpty()) { echo $jobs->extract(), "\n"; }

Пароль
Отчёт A
Отчёт B

Второй аргумент insert теперь массив приоритета из двух полей. Встроенная куча вызывает compare с двумя такими массивами, не со строками задания. Сначала return отдаёт знак сравнения level. При одинаковом level меньший sequence получает больший приоритет через обратное сравнение. Возврат compare используется только алгоритмом; extract позже возвращает строку. Счётчик sequence должен быть уникальным и возрастающим в пределах этого планировщика.

<?php
declare(strict_types=1);

$readings = new SplFixedArray(3);
$readings[0] = 18;
$readings[2] = 21;
echo 'Первое показание: ', $readings[0], "\n";
echo 'Мест: ', $readings->getSize(), "\n";
foreach ($readings as $index => $value) {
    echo $index, ': ', $value === null ? 'нет замера' : $value, "\n";
}

Первое показание: 18
Мест: 3
0: 18
1: нет замера
2: 21

Число 3 в конструкторе задаёт количество мест: индексы 0, 1, 2. Каждое сначала содержит null. Квадратные скобки выбирают место; запись меняет его значение. count/getSize считают места, включая незаполненные. foreach проходит все три; строгая проверка === null выбирает подпись отсутствующего измерения, сохраняя настоящий ноль.

<?php
declare(strict_types=1);

$readings = SplFixedArray::fromArray([18, 19]);
$readings->setSize(4);
$readings[3] = 22;
echo 'До сокращения: ', json_encode($readings), "\n";
$readings->setSize(2);
$readings->setSize(4);
echo 'После расширения: ', json_encode($readings), "\n";

До сокращения: [18,19,null,22]
После расширения: [18,19,null,null]

fromArray создаёт новый контейнер из обычного массива. setSize(4) добавляет два null. Сокращение до 2 уничтожает значения за новой границей; повторное увеличение не возвращает 22. json_encode здесь только делает всю уже объяснённую структуру видимой: внутри скобок значения идут по индексам.

<?php
declare(strict_types=1);

$readings = new SplFixedArray(3);
$readings->offsetSet(1, 0);
if ($readings->offsetExists(1)) {
    echo 'Есть показание: ', $readings->offsetGet(1), "\n";
}
$readings->offsetUnset(1);
if (!$readings->offsetExists(1)) { echo "Показание очищено\n"; }
echo 'Мест после очистки: ', $readings->count(), "\n";
echo 'В ячейке: ', $readings[1] === null ? 'null' : 'другое', "\n";

Есть показание: 0
Показание очищено
Мест после очистки: 3
В ячейке: null

offsetSet/offsetGet соответствуют записи/чтению квадратными скобками. offsetUnset, как unset($readings[1]), очищает значение до null, но не сжимает контейнер. offsetExists имеет isset-смысл: для null false, для 0 true. Проверку допустимого номера выполняют отдельно: 0 <= индекс < getSize().

<?php
declare(strict_types=1);

$readings = SplFixedArray::fromArray([18, 22]);
$iterator = $readings->getIterator();
$iterator->rewind();
while ($iterator->valid()) {
    echo 'Замер ', $iterator->key(), ': ', $iterator->current(), "\n";
    $iterator->next();
}
$iterator->rewind();
echo 'Снова первый: ', $iterator->current(), "\n";

Замер 0: 18
Замер 1: 22
Снова первый: 18

С PHP 8 SplFixedArray реализует IteratorAggregate: контейнер выдаёт отдельный Iterator. rewind/current/key/next/valid вызываются у $iterator, не у $readings. getIterator возвращает объект в переменную; затем цикл читает индекс и значение, продвигается, останавливается. Значения не удаляются.

<?php
$input = ['currency' => 'RUB', 'pageSize' => 20];
$settings = new ArrayObject($input);

$settings['pageSize'] = 50;
echo 'В объекте: ', $settings['pageSize'], "\n";
echo 'В исходном массиве: ', $input['pageSize'], "\n";
echo 'Записей: ', $settings->count(), "\n";

В объекте: 50
В исходном массиве: 20
Записей: 2

new ArrayObject($input) создаёт объект-обёртку с собственным хранилищем. Квадратные скобки вызывают методы ArrayAccess: чтение соответствует offsetGet, присваивание — offsetSet. Изменение обёртки не переписывает переменную $input. count() считает записи текущего хранилища.

<?php
$state = (object) ['status' => 'new'];
$order = new ArrayObject(['quantity' => 2, 'state' => $state]);
$copy = $order->getArrayCopy();

$copy['quantity'] = 5;
$copy['state']->status = 'checked';

echo 'Количество в объекте: ', $order['quantity'], "\n";
echo 'Количество в копии: ', $copy['quantity'], "\n";
echo 'Статус в объекте: ', $order['state']->status, "\n";

Количество в объекте: 2
Количество в копии: 5
Статус в объекте: checked

getArrayCopy возвращает отдельный PHP-массив. Скаляр quantity меняется только в копии. Копирование неглубокое: обе структуры всё ещё ссылаются на тот же вложенный объект $state, поэтому его свойство изменилось в обеих. Для независимого снимка вложенные объекты надо копировать по выбранным правилам домена.

<?php
$profile = new ArrayObject(
    ['name' => 'Анна'],
    ArrayObject::ARRAY_AS_PROPS
);

echo 'Флаг: ', $profile->getFlags(), "\n";
echo 'Имя: ', $profile->name, "\n";
$profile->city = 'Казань';
echo 'Через скобки: ', $profile['city'], "\n";

$profile->setFlags(0);
echo 'Флаг после возврата: ', $profile->getFlags(), "\n";

Флаг: 2
Имя: Анна
Через скобки: Казань
Флаг после возврата: 0

ARRAY_AS_PROPS равен 2 и перенаправляет $profile->name к записи name. Присваивание свойства добавляет запись city, которую видно и через скобки. setFlags(0) отключает этот режим. Такой синтаксис удобен только при контролируемых ключах: запись с именем метода или настоящего свойства может сделать код двусмысленным.

<?php
class UpperTitleIterator extends ArrayIterator {
    public function current(): mixed {
        return strtoupper((string) parent::current());
    }
}

$titles = new ArrayObject(['draft' => 'php guide']);
echo 'Итератор по умолчанию: ', $titles->getIteratorClass(), "\n";
$titles->setIteratorClass(UpperTitleIterator::class);
echo 'Выбранный итератор: ', $titles->getIteratorClass(), "\n";

$iterator = $titles->getIterator();
echo 'Класс экземпляра: ', $iterator::class, "\n";
echo 'При обходе: ', $iterator->current(), "\n";
echo 'В хранилище: ', $titles['draft'], "\n";

Итератор по умолчанию: ArrayIterator
Выбранный итератор: UpperTitleIterator
Класс экземпляра: UpperTitleIterator
При обходе: PHP GUIDE
В хранилище: php guide

setIteratorClass сохраняет имя подкласса ArrayIterator. getIterator создаёт новый экземпляр этого класса. Переопределённый current форматирует отдаваемое значение, но не меняет хранилище: квадратные скобки по-прежнему возвращают исходную строку.

<?php
class Document {
    public function __construct(public string $number) {}
}

$first = new Document('A-17');
$second = new Document('A-17');
$states = new SplObjectStorage();
$states[$first] = 'проверен';
$states[$second] = 'ожидает';

echo 'Объектов: ', $states->count(), "\n";
echo 'Первый: ', $states[$first], "\n";
echo 'Второй: ', $states[$second], "\n";

Объектов: 2
Первый: проверен
Второй: ожидает

Одинаковое поле number не делает два экземпляра одним ключом. SplObjectStorage сопоставляет info конкретной идентичности объекта. Запись $states[$first] = ... вызывает offsetSet; чтение — offsetGet. Это удобно для временной метаинформации, которую не надо добавлять в сам Document.

<?php
$job = (object) ['id' => 42];
$states = new SplObjectStorage();
$states[$job] = ['attempt' => 1, 'status' => 'queued'];

$info = $states[$job];
$info['attempt']++;
$info['status'] = 'sent';
$states[$job] = $info;

echo 'Попытка: ', $states[$job]['attempt'], "\n";
echo 'Статус: ', $states[$job]['status'], "\n";

Попытка: 2
Статус: sent

offsetGet возвращает metadata по значению. Поэтому массив сначала читается в $info, изменяется и целиком записывается обратно. Выражение $states[$job]["attempt"]++ пытается косвенно менять временный результат и не является надёжным обновлением хранилища.

<?php
class Task {
    public function __construct(public string $name) {}
}
$build = new Task('Сборка');
$test = new Task('Тесты');
$states = new SplObjectStorage();
$states[$build] = 'done';
$states[$test] = 'waiting';

$states->rewind();
while ($states->valid()) {
    $position = $states->key();
    $task = $states->current();
    $info = $states->getInfo();
    echo $position, ': ', $task->name, ' — ', $info, "\n";
    $states->next();
}

0: Сборка — done
1: Тесты — waiting

rewind ставит итератор на первую запись. valid разрешает current/getInfo/key. current возвращает объект-ключ, getInfo — связанную метаинформацию, key — позицию обхода 0,1… . next переводит к следующей записи. Позиция не является ID объекта.

<?php
$storage = new SplObjectStorage();
$object = (object) ['id' => 5];
$weak = WeakReference::create($object);
$storage[$object] = 'held';
unset($object);
gc_collect_cycles();
echo 'Пока в storage: ', $weak->get() !== null ? 'жив' : 'удалён', "\n";

$storage->rewind();
$held = $storage->current();
$storage->offsetUnset($held);
unset($held);
gc_collect_cycles();
echo 'После удаления: ', $weak->get() !== null ? 'жив' : 'удалён', "\n";

Пока в storage: жив
После удаления: удалён

SplObjectStorage хранит сильную ссылку на object-key, поэтому unset внешней переменной не уничтожает объект. После offsetUnset и удаления временной $held сильных ссылок не остаётся, WeakReference возвращает null. Если таблица не должна продлевать жизнь объектов, рассмотрите WeakMap.

<?php
declare(strict_types=1);

$web = new ArrayIterator(['web-42', 'web-43']);
$shop = new ArrayIterator(['shop-7']);
$orders = new AppendIterator();
$orders->append($web);
$orders->append($shop);
foreach ($orders as $key => $order) {
    echo $orders->getIteratorIndex(), '|', $key, '|', $order, "\n";
}
echo 'Источников: ', $orders->getArrayIterator()->count(), "\n";

0|0|web-42
0|1|web-43
1|0|shop-7
Источников: 2

append() сохранил оба объекта-источника. Во время foreach getIteratorIndex() показывает, откуда пришла строка; key() остаётся ключом конкретного источника. getArrayIterator() здесь считает подключённые источники, а не заказы.

<?php
declare(strict_types=1);

$all = new AppendIterator();
$all->append(new ArrayIterator(['A-1']));
$all->append(new ArrayIterator(['B-1', 'B-2']));
$all->rewind();
while ($all->valid()) {
    echo $all->getIteratorIndex(), ':', $all->key(), '=', $all->current(), "\n";
    $all->next();
}
$all->rewind();
echo 'Снова первый: ', $all->current(), "\n";

0:0=A-1
1:0=B-1
1:1=B-2
Снова первый: A-1

rewind() поставил курсор в начало первого непустого источника. Цикл проверял valid(), читал current()/key(), затем next() переходил дальше; после конца повторный rewind() вернул первый элемент, потому что оба ArrayIterator повторяемы.

<?php
declare(strict_types=1);

$catalog = new ArrayIterator([
    'sku-10' => 'Кисть',
    'sku-20' => 'Лак',
    'sku-30' => 'Валик',
]);
$catalog->seek(1);
echo $catalog->key(), ': ', $catalog->current(), "\n";
$catalog->next();
echo $catalog->key(), ': ', $catalog->current(), "\n";

sku-20: Лак
sku-30: Валик

seek(1) выбрал вторую позицию порядка обхода, хотя её ключ — sku-20. current() вернул название, key() — артикул, next() передвинул курсор на третью позицию.

<?php
declare(strict_types=1);

$stock = new ArrayIterator(['brush' => 2]);
$stock->offsetSet('paint', 3);
$stock->append(7);
echo 'brush exists: ', $stock->offsetExists('brush') ? 'yes' : 'no', "\n";
echo 'paint: ', $stock->offsetGet('paint'), "\n";
$stock->offsetUnset('brush');
echo 'count: ', $stock->count(), "\n";
echo json_encode($stock->getArrayCopy(), JSON_UNESCAPED_UNICODE), "\n";

brush exists: yes
paint: 3
count: 2
{"paint":3,"0":7}

offsetSet("paint", 3) создал именованный элемент, append(7) выбрал следующий целочисленный ключ 0. После offsetUnset("brush") count() равен двум, а getArrayCopy() вернул независимое обычное представление данных.

<?php
declare(strict_types=1);

$byValue = new ArrayIterator(['b' => 10, 'a' => 20]);
$byValue->asort();
echo 'asort: ', json_encode($byValue->getArrayCopy()), "\n";
$byKey = new ArrayIterator(['b' => 10, 'a' => 20]);
$byKey->ksort();
echo 'ksort: ', json_encode($byKey->getArrayCopy()), "\n";

asort: {"b":10,"a":20}
ksort: {"a":20,"b":10}

asort() сравнил значения 10 и 20 и сохранил ключи. ksort() сравнил ключи a и b. Обе операции изменили порядок самого объекта.

<?php
declare(strict_types=1);

$rows = new EmptyIterator();
$rows->rewind();
echo 'valid: ', $rows->valid() ? 'yes' : 'no', "\n";
$rows->next();
echo 'after next: ', $rows->valid() ? 'yes' : 'no', "\n";
foreach ($rows as $row) { echo 'unreachable', "\n"; }
echo "Обход завершён без строк\n";

valid: no
after next: no
Обход завершён без строк

rewind() и next() ничего не сделали, valid() всегда вернул false, поэтому foreach не вызвал тело. Это корректная пустота, а не ошибка чтения.

<?php
declare(strict_types=1);

$rows = new EmptyIterator();
foreach (['current', 'key'] as $method) {
    try {
        $rows->$method();
    } catch (Exception $error) {
        echo $method, ': ', $error::class, "\n";
    }
}
echo 'valid: ', $rows->valid() ? 'yes' : 'no', "\n";

current: BadMethodCallException
key: BadMethodCallException
valid: no

current() и key() завершились BadMethodCallException, которое пример перехватил. valid() остаётся безопасной проверкой и возвращает false. Точный класс подтверждается запуском текущего runtime.

<?php
declare(strict_types=1);

$rotation = new InfiniteIterator(new ArrayIterator(['Анна', 'Борис']));
$fiveShifts = new LimitIterator($rotation, 0, 5);
$shift = 1;
foreach ($fiveShifts as $person) {
    echo $shift, ': ', $person, "\n";
    $shift++;
}

1: Анна
2: Борис
3: Анна
4: Борис
5: Анна

InfiniteIterator после Бориса снова начал внутренний ArrayIterator с Анны. Его исходные ключи тоже повторяются, поэтому отдельный счётчик $shift нумерует итоговое расписание. Внешний LimitIterator остановил обход после пяти значений; без него foreach не завершился бы.

<?php
declare(strict_types=1);

$delays = new InfiniteIterator(new ArrayIterator([1, 2, 5]));
$attempts = new LimitIterator($delays, 0, 7);
$attempt = 1;
foreach ($attempts as $seconds) {
    echo 'Попытка ', $attempt, ': пауза ', $seconds, " сек.\n";
    $attempt++;
}

Попытка 1: пауза 1 сек.
Попытка 2: пауза 2 сек.
Попытка 3: пауза 5 сек.
Попытка 4: пауза 1 сек.
Попытка 5: пауза 2 сек.
Попытка 6: пауза 5 сек.
Попытка 7: пауза 1 сек.

next() InfiniteIterator сам перемотал внутренний источник после третьего значения. Ключи внутреннего массива повторяются, поэтому номер попытки хранится отдельно. Пример только печатает план: он не вызывает sleep() и не отправляет запросы. Семь попыток ограничены явно.

<?php
declare(strict_types=1);

$period = new DatePeriod(
    new DateTimeImmutable('2026-10-12'),
    new DateInterval('P1D'),
    new DateTimeImmutable('2026-10-15')
);
$days = new IteratorIterator($period);
foreach ($days as $day) {
    echo $day->format('Y-m-d'), "\n";
}
echo 'inner: ', $days->getInnerIterator()::class, "\n";

2026-10-12
2026-10-13
2026-10-14
inner: InternalIterator

IteratorIterator передал foreach три даты до исключительной конечной даты. Поскольку DatePeriod — Traversable, но не Iterator, PHP показывает внутренний адаптер InternalIterator; getInnerIterator() возвращает именно активный Iterator-слой, а не массив-копию и не обязуется вернуть исходный DatePeriod.

<?php
declare(strict_types=1);

$inner = new ArrayIterator(['new', 'paid']);
$outer = new IteratorIterator($inner);
$outer->rewind();
while ($outer->valid()) {
    echo $outer->key(), '=', $outer->current(), "\n";
    $outer->next();
}
$outer->rewind();
echo 'again: ', $outer->current(), "\n";

0=new
1=paid
again: new

Каждый outer-метод делегировал действие inner ArrayIterator. После конца rewind() снова перемотал повторяемый источник; обёртка не создала второго набора данных.

<?php
declare(strict_types=1);

$catalog = new ArrayIterator(['A', 'B', 'C', 'D', 'E']);
$page = new LimitIterator($catalog, 2, 2);
foreach ($page as $key => $item) {
    echo 'source=', $page->getPosition(), '; key=', $key, '; item=', $item, "\n";
}
$page->seek(3);
echo 'seek result: ', $page->current(), "\n";

source=2; key=2; item=C
source=3; key=3; item=D
seek result: D

Конструктор ограничил видимый диапазон C–D. getPosition() показал абсолютную позицию внутреннего источника. seek(3) допустим внутри окна и выбрал D.

<?php
declare(strict_types=1);

$cycle = new InfiniteIterator(new ArrayIterator(['day', 'night']));
$limited = new LimitIterator($cycle, 1, 4);
$limited->rewind();
$position = 1;
while ($limited->valid()) {
    echo $position, ':', $limited->current(), "\n";
    $position++;
    $limited->next();
}

1:night
2:day
3:night
4:day

rewind() LimitIterator позиционировал внутренний цикл на offset 1. Ключи InfiniteIterator повторяют ключи day/night, поэтому итоговую позицию считает отдельная переменная. valid() стал false после четырёх элементов, хотя сам InfiniteIterator оставался способен продолжаться.

<?php
declare(strict_types=1);

$names = new ArrayIterator(['brush', 'paint']);
$qty = new ArrayIterator([2, 0]);
$rows = new MultipleIterator(MultipleIterator::MIT_NEED_ALL | MultipleIterator::MIT_KEYS_ASSOC);
$rows->attachIterator($names, 'name');
$rows->attachIterator($qty, 'qty');
foreach ($rows as $keys => $row) {
    echo $keys['name'], ':', $row['name'], '=', $row['qty'], "\n";
}

0:brush=2
1:paint=0

attachIterator() закрепил имена name и qty. current() сформировал ассоциативную пару, key() — ассоциативную пару исходных ключей. MIT_NEED_ALL потребовал наличие обеих колонок.

<?php
declare(strict_types=1);

$left = new ArrayIterator(['A']);
$right = new ArrayIterator([10, 20]);
$rows = new MultipleIterator();
$rows->attachIterator($left);
$rows->attachIterator($right);
echo 'count: ', $rows->countIterators(), "\n";
echo 'contains left: ', $rows->containsIterator($left) ? 'yes' : 'no', "\n";
$rows->setFlags(MultipleIterator::MIT_NEED_ANY | MultipleIterator::MIT_KEYS_NUMERIC);
echo 'need-any: ', (($rows->getFlags() & MultipleIterator::MIT_NEED_ALL) === MultipleIterator::MIT_NEED_ANY) ? 'yes' : 'no', "\n";
foreach ($rows as $row) { echo json_encode($row), "\n"; }
$rows->detachIterator($left);
echo 'after detach: ', $rows->countIterators(), "\n";

count: 2
contains left: yes
need-any: yes
["A",10]
[null,20]
after detach: 1

MIT_NEED_ANY разрешил второй ряд; отсутствующее значение стало null. Эта константа равна нулевому варианту битовой группы, поэтому режим проверяется сравнением замаскированной группы, а не обычным truthy-тестом. containsIterator() проверил идентичность объекта. detachIterator() отключил именно $left, и countIterators() уменьшился до одного.

<?php
declare(strict_types=1);

$rows = new MultipleIterator();
$rows->attachIterator(new ArrayIterator(['x', 'y']));
$rows->attachIterator(new ArrayIterator([1, 2]));
$rows->rewind();
while ($rows->valid()) {
    echo json_encode($rows->key()), '=', json_encode($rows->current()), "\n";
    $rows->next();
}
$rows->rewind();
echo 'again: ', json_encode($rows->current()), "\n";

[0,0]=["x",1]
[1,1]=["y",2]
again: ["x",1]

rewind()/next()/valid() управляли обоими внутренними курсорами. key() и current() вернули составные массивы. Повторный rewind() сработал, потому что оба ArrayIterator повторяемы.

<?php
declare(strict_types=1);

$stream = new NoRewindIterator(new ArrayIterator(['A', 'B', 'C']));
foreach ($stream as $value) {
    echo 'first: ', $value, "\n";
    if ($value === 'B') { break; }
}
foreach ($stream as $value) {
    echo 'second: ', $value, "\n";
}

first: A
first: B
second: B
second: C

После break курсор всё ещё указывал на B. Второй foreach вызвал rewind(), но NoRewindIterator его проигнорировал, поэтому B был прочитан повторно, затем next() перевёл курсор к C. Класс защищает от перемотки, но не от повторного чтения current().

<?php
declare(strict_types=1);

$stream = new NoRewindIterator(new ArrayIterator(['header', 'body']));
$stream->rewind();
echo $stream->key(), ':', $stream->current(), "\n";
$stream->next();
$stream->rewind();
echo $stream->key(), ':', $stream->current(), "\n";
$stream->next();
echo 'valid: ', $stream->valid() ? 'yes' : 'no', "\n";

0:header
1:body
valid: no

Первый rewind() позволил начать с header. После next() курсор был на body; второй rewind() сохранил эту позицию. Ещё один next() закончил источник, valid() вернул false.

<?php
declare(strict_types=1);

$steps = new CachingIterator(
    new ArrayIterator(['received', 'paid', 'shipped'])
);

foreach ($steps as $step) {
    echo $steps->key(), ':', (string) $steps;
    echo $steps->hasNext() ? ' -> ' : "\n";
}

0:received -> 1:paid -> 2:shipped

foreach вызвал rewind(), valid(), current() и next(). На каждой позиции hasNext() заглянул на один шаг вперёд, не потребляя соседний элемент. Поэтому разделитель появился только между значениями. __toString() безопасен здесь, потому что значения — строки и действует стандартный CALL_TOSTRING.

<?php
declare(strict_types=1);

$orders = new CachingIterator(
    new ArrayIterator([
        'order-101' => 'new',
        'order-102' => 'paid',
        'order-103' => 'sent',
    ]),
    CachingIterator::FULL_CACHE
);

$orders->rewind();
echo 'key=', $orders->key(), '; full-cache=',
    ($orders->getFlags() & CachingIterator::FULL_CACHE) !== 0 ? 'yes' : 'no',
    "\n";
echo json_encode($orders->getCache()), "\n";

$orders->next();
echo json_encode($orders->getCache()), "\n";
echo 'count=', count($orders),
    '; exists=', isset($orders['order-102']) ? 'yes' : 'no',
    '; value=', $orders['order-102'], "\n";

$orders['review'] = 'manual';
echo json_encode($orders->getCache()), "\n";
unset($orders['review']);
echo json_encode($orders->getCache()), "\n";

key=order-101; full-cache=yes
{"order-101":"new"}
{"order-101":"new","order-102":"paid"}
count=2; exists=yes; value=paid
{"order-101":"new","order-102":"paid","review":"manual"}
{"order-101":"new","order-102":"paid"}

FULL_CACHE добавил текущую запись при rewind() и следующую при next(). getCache(), count() и ArrayAccess работают с накопленным кешем: непрочитанный order-103 ещё отсутствует. Запись review появилась только в кеше и была удалена; это не команда изменить исходный источник.

<?php
declare(strict_types=1);

function cachingFlagNames(int $flags): string
{
    $names = [];
    foreach (['TOSTRING_USE_KEY', 'TOSTRING_USE_CURRENT', 'FULL_CACHE'] as $name) {
        $value = constant("CachingIterator::$name");
        if (($flags & $value) === $value) {
            $names[] = $name;
        }
    }
    return implode('|', $names);
}

$items = new CachingIterator(
    new ArrayIterator(['SKU-1' => 'Brush', 'SKU-2' => 'Paint']),
    CachingIterator::FULL_CACHE | CachingIterator::TOSTRING_USE_KEY
);

$items->rewind();
echo cachingFlagNames($items->getFlags()), ':', (string) $items,
    '; next=', $items->hasNext() ? 'yes' : 'no', "\n";

$items->setFlags(
    CachingIterator::FULL_CACHE | CachingIterator::TOSTRING_USE_CURRENT
);
echo cachingFlagNames($items->getFlags()), ':', (string) $items, "\n";

$items->next();
echo cachingFlagNames($items->getFlags()), ':', (string) $items,
    '; next=', $items->hasNext() ? 'yes' : 'no', "\n";

TOSTRING_USE_KEY|FULL_CACHE:SKU-1; next=yes
TOSTRING_USE_CURRENT|FULL_CACHE:Brush
TOSTRING_USE_CURRENT|FULL_CACHE:Paint; next=no

getFlags() вернул битовую маску. Оператор & проверил отдельные биты, а | объединил режимы. setFlags() заменил всю маску, поэтому FULL_CACHE включён повторно вместе с новым TOSTRING_USE_CURRENT. hasNext() подтвердил сосед только на первой позиции.

<?php
declare(strict_types=1);

$orders = new ArrayIterator([
    ['id' => 101, 'status' => 'new'],
    ['id' => 102, 'status' => 'paid'],
    ['id' => 103, 'status' => 'paid'],
]);

function isPaidOrder(array $order): bool
{
    return $order['status'] === 'paid';
}

$paidOrders = new CallbackFilterIterator($orders, 'isPaidOrder');
foreach ($paidOrders as $order) {
    echo 'send receipt #', $order['id'], "\n";
}

send receipt #102
send receipt #103

isPaidOrder — предикат: вопрос с ответом true или false. Callback — ссылка на вызываемую функцию; строка isPaidOrder передана конструктору, а итератор вызвал её для каждой строки. true оставил заказ, false пропустил его.

<?php
declare(strict_types=1);

$stock = new ArrayIterator([
    'web-brush' => 3,
    'store-paint' => 7,
    'web-tape' => 0,
    'web-gloves' => 2,
]);

$webAvailable = new CallbackFilterIterator(
    $stock,
    function (int $quantity, string $key, Iterator $iterator) use ($stock): bool {
        return $iterator === $stock
            && str_starts_with($key, 'web-')
            && $quantity > 0;
    }
);

foreach ($webAvailable as $sku => $quantity) {
    echo "$sku=$quantity\n";
}

web-brush=3
web-gloves=2

Анонимный callback получил значение, ключ и внутренний Iterator. Проверка идентичности показывает, какой именно объект приходит третьим аргументом; в обычном предикате она чаще не нужна. Условия соединены &&: только true по всем трём проверкам оставляет элемент.

<?php
declare(strict_types=1);

final class AvailableProducts extends FilterIterator
{
    public function accept(): bool
    {
        $product = parent::current();
        return is_array($product) && $product['stock'] > 0;
    }
}

$catalogs = [
    new ArrayIterator([
        ['name' => 'Brush', 'stock' => 2],
        ['name' => 'Paint', 'stock' => 0],
    ]),
    new ArrayIterator([
        ['name' => 'Tape', 'stock' => 4],
        ['name' => 'Gloves', 'stock' => 0],
    ]),
];

foreach ($catalogs as $catalog) {
    foreach (new AvailableProducts($catalog) as $product) {
        echo $product['name'], "\n";
    }
}

Brush
Tape

FilterIterator абстрактный: его нельзя создать напрямую, поэтому AvailableProducts реализует accept(). parent::current() читает текущую строку внутреннего итератора. Один класс отфильтровал два разных ArrayIterator без копирования условия.

<?php
declare(strict_types=1);

final class PriceAtLeast extends FilterIterator
{
    public function __construct(Iterator $iterator, private int $minimum)
    {
        parent::__construct($iterator);
    }

    public function accept(): bool
    {
        return parent::current() >= $this->minimum;
    }
}

$prices = new PriceAtLeast(
    new ArrayIterator(['pen' => 40, 'brush' => 120, 'paint' => 300]),
    100
);

$prices->rewind();
while ($prices->valid()) {
    echo $prices->key(), '=', $prices->current(), "\n";
    $prices->next();
}

brush=120
paint=300

rewind() перемотал источник и сразу продвинул его мимо pen=40 до первого accept() === true. current()/key() прочитали brush. next() снова двигал внутренний курсор до следующего принятого элемента, а valid() завершил цикл после paint.

<?php
declare(strict_types=1);

$images = new RegexIterator(
    new ArrayIterator(['notes.txt', 'PHOTO.JPG', 'icon.png']),
    '/\.(?:jpe?g|png)$/i'
);
foreach ($images as $name) {
    echo $name, "\n";
}

$published = new RegexIterator(
    new ArrayIterator([
        'draft-1' => 'A',
        'order-2' => 'B',
        'draft-3' => 'C',
    ]),
    '/^draft-/'
);
$published->setFlags(RegexIterator::USE_KEY | RegexIterator::INVERT_MATCH);
echo 'flags=', $published->getFlags(),
    '; regex=', $published->getRegex(), "\n";
foreach ($published as $key => $value) {
    echo "$key=$value\n";
}

PHOTO.JPG
icon.png
flags=3; regex=/^draft-/
order-2=B

Стандартный MATCH оставил совпавшие значения; модификатор i отключил зависимость от регистра. Во втором фильтре USE_KEY перенёс проверку на ключ, INVERT_MATCH инвертировал решение, а | объединил оба флага. Для статуса заказа из отдельного поля лучше callback со строгим сравнением, а не regex.

<?php
declare(strict_types=1);

$orders = new RegexIterator(
    new ArrayIterator(['order #104 costs 3500', 'broken record']),
    '/order #(?<id>\d+)/'
);
$orders->setMode(RegexIterator::GET_MATCH);
$orders->setPregFlags(PREG_OFFSET_CAPTURE);

foreach ($orders as $match) {
    echo 'id=', $match['id'][0],
        '; offset=', $match['id'][1], "\n";
}

id=104; offset=7

GET_MATCH заменил current() массивом результата preg_match(). Именованная группа id дала понятный ключ. PREG_OFFSET_CAPTURE превратил каждое совпадение в пару [текст, смещение]. broken record не совпал и не попал в обход.

<?php
declare(strict_types=1);

$logs = new RegexIterator(
    new ArrayIterator([
        'added SKU-12 and SKU-77',
        'nothing',
        'removed SKU-5',
    ]),
    '/SKU-\d+/',
    RegexIterator::ALL_MATCHES
);

foreach ($logs as $matches) {
    echo implode(',', $matches[0]), "\n";
}

SKU-12,SKU-77
SKU-5

ALL_MATCHES использовал семантику preg_match_all(): $matches[0] содержит все полные совпадения текущей строки. Строка nothing отфильтрована. Если вход уже является массивом SKU, цикл и строгая проверка структуры яснее регулярного выражения.

<?php
declare(strict_types=1);

$lines = new RegexIterator(
    new ArrayIterator(['php, spl; iterators', 'single']),
    '/[\s,;]+/',
    RegexIterator::SPLIT
);
$lines->setPregFlags(PREG_SPLIT_NO_EMPTY);

echo 'mode=', $lines->getMode(),
    '; preg-flags=', $lines->getPregFlags(), "\n";
foreach ($lines as $parts) {
    echo implode('|', $parts), "\n";
}

mode=3; preg-flags=1
php|spl|iterators

SPLIT возвращает результат preg_split() для совпавших строк. PREG_SPLIT_NO_EMPTY убрал пустые части. Строка single не содержит разделителя и поэтому не была принята итератором; если её тоже нужно сохранить как один тег, обычный цикл с preg_split() для каждой строки выразит требование точнее.

<?php
declare(strict_types=1);

$codes = new RegexIterator(
    new ArrayIterator(['header', 'order-17', 'order-25']),
    '/^order-(\d+)$/',
    RegexIterator::REPLACE
);
$codes->replacement = 'ID:$1';

foreach ($codes as $key => $code) {
    echo "$key:$code\n";
}

1:ID:17
2:ID:25

REPLACE выполнил preg_replace() и вернул преобразованные совпавшие элементы с исходными ключами. header исчез: RegexIterator остаётся фильтром и не обещает сохранить несовпавшие строки. Если нужен map, сохраняющий каждый элемент, используйте обычный цикл или array_map(). Официальная документация помечает REPLACE как реализованный не полностью, поэтому критичный код требует теста целевой версии.

<?php
$catalog = [
    'lamps' => ['desk' => 3, 'floor' => 2],
    'delivery' => 'free',
    'cables' => ['usb' => 8],
];
foreach ($catalog as $name => $value) {
    if (is_array($value)) {
        echo $name, ': ', count($value), " дочерних\n";
    }
}

lamps: 2 дочерних
cables: 1 дочерних

Обычный foreach полезно увидеть первым: ParentIterator автоматизирует именно эту проверку, а не создаёт новое дерево.

<?php
$menu = new RecursiveArrayIterator([
    'shop' => ['catalog' => '/catalog', 'cart' => '/cart'],
    'contacts' => '/contacts',
    'help' => ['faq' => '/faq'],
]);
$parents = new ParentIterator($menu);
foreach ($parents as $key => $children) {
    echo $key, ': ', count($children), " пунктов\n";
}

shop: 2 пунктов
help: 1 пунктов

Результат содержит shop и help, но не contacts: строка является листом, даже если по смыслу это пункт меню.

<?php
$order = [
    'id' => 41,
    'customer' => ['name' => 'Ирина', 'city' => 'Тула'],
];
foreach ($order as $key => $value) {
    echo $key, ': ', is_array($value) ? 'вложенный массив' : $value, "\n";
}

id: 41
customer: вложенный массив

RecursiveArrayIterator не меняет эту модель; он даёт единый протокол hasChildren()/getChildren().

<?php
$tree = new RecursiveArrayIterator([
    'id' => 41,
    'customer' => ['name' => 'Ирина', 'city' => 'Тула'],
]);
foreach ($tree as $key => $value) {
    echo $key, ': ', $tree->hasChildren() ? 'ветка' : 'лист', "\n";
}

id: лист
customer: ветка

Это ещё не рекурсивный обход: foreach остаётся на первом уровне, а решение о спуске принимает вызывающий код.

<?php
$cache = new RecursiveCachingIterator(
    new RecursiveArrayIterator(['draft', 'review', 'publish']),
    CachingIterator::FULL_CACHE
);
foreach ($cache as $stage) {
    echo $stage, ' | дальше: ', $cache->hasNext() ? 'да' : 'нет', "\n";
}

draft | дальше: да
review | дальше: да
publish | дальше: нет

RecursiveCachingIterator добавляет к обычному курсору кэш; рекурсивная часть понадобится, когда текущий элемент окажется ветвью.

<?php
$cache = new RecursiveCachingIterator(
    new RecursiveArrayIterator(['shop' => ['cart', 'checkout']]),
    CachingIterator::FULL_CACHE
);
$cache->rewind();
echo 'Ветка: ', $cache->hasChildren() ? 'да' : 'нет', "\n";
$children = $cache->getChildren();
foreach ($children as $page) {
    echo $page, "\n";
}

Ветка: да
cart
checkout

Кэш каждого уровня отдельный; это помогает форматировать дерево, но увеличивает использование памяти.

<?php
$config = [
    'database' => ['host' => 'db.local', 'password' => 'secret'],
    'debug' => true,
];
foreach ($config as $group => $value) {
    if (is_array($value)) {
        foreach ($value as $key => $item) {
            if ($key !== 'password') echo $group, '.', $key, '=', $item, "\n";
        }
    }
}

database.host=db.local

Это важная граница: удалив родителя слишком рано, код уже не доберётся до разрешённого host.

<?php
$source = new RecursiveArrayIterator([
    'database' => ['host' => 'db.local', 'password' => 'secret'],
    'debug' => true,
]);
$safe = new RecursiveCallbackFilterIterator(
    $source,
    function (mixed $current, mixed $key, RecursiveIterator $iterator): bool {
        return $iterator->hasChildren() || $key !== 'password';
    }
);
$flat = new RecursiveIteratorIterator($safe, RecursiveIteratorIterator::LEAVES_ONLY);
foreach ($flat as $key => $value) echo $key, '=', var_export($value, true), "\n";

host='db.local'
debug=true

Так путь к host сохраняется, password исключается, а корневой лист debug остаётся. Фильтр не маскирует исходный массив.

<?php
$dir = new DirectoryIterator(__DIR__ . '/fixture');
$names = [];
foreach ($dir as $entry) {
    if (!$entry->isDot()) $names[] = $entry->getFilename();
}
sort($names);
echo implode(', ', $names), "\n";

docs, root.txt, src

Вложенные api.md и App.php пока не видны: для дерева нужен рекурсивный источник.

<?php
$flags = FilesystemIterator::SKIP_DOTS;
$root = new RecursiveDirectoryIterator(__DIR__ . '/fixture', $flags);
$flat = new RecursiveIteratorIterator($root, RecursiveIteratorIterator::LEAVES_ONLY);
$paths = [];
foreach ($flat as $file) {
    if ($file->isFile()) $paths[] = str_replace('\\', '/', $flat->getSubPathname());
}
sort($paths);
echo implode("\n", $paths), "\n";
echo 'FOLLOW_SYMLINKS: ', ($flags & FilesystemIterator::FOLLOW_SYMLINKS) ? 'да' : 'нет', "\n";

docs/api.md
docs/readme.txt
root.txt
src/App.php
FOLLOW_SYMLINKS: нет

SKIP_DOTS убирает . и ... FOLLOW_SYMLINKS намеренно не включён: учебный обход не следует по ссылкам и не рискует попасть в цикл.

<?php
class PublicConfigFilter extends RecursiveFilterIterator {
    public function accept(): bool {
        return $this->hasChildren() || !str_starts_with((string) $this->key(), '_');
    }
}
$filter = new PublicConfigFilter(new RecursiveArrayIterator([
    'app' => ['name' => 'Store', '_token' => 'secret'],
]));
foreach (new RecursiveIteratorIterator($filter) as $key => $value) echo $key, '=', $value, "\n";

name=Store

Родитель app остаётся для спуска; служебный _token исключается только на уровне листа.

<?php
class AvailableFilter extends RecursiveFilterIterator {
    public function accept(): bool {
        return $this->hasChildren() || (int) $this->current() > 0;
    }
}
$filter = new AvailableFilter(new RecursiveArrayIterator([
    'lamps' => ['desk' => 2, 'floor' => 0],
    'cables' => ['usb' => 5],
]));
foreach (new RecursiveIteratorIterator($filter) as $sku => $qty) echo $sku, '=', $qty, "\n";

desk=2
usb=5

За счёт сохранённых parents обходчик достигает desk и usb; пустой floor отсеивается.

<?php
$config = ['app' => ['cache' => ['driver' => 'file'], 'debug' => true], 'version' => '1'];
function flatten(array $items, string $prefix = ''): void {
    foreach ($items as $key => $value) {
        $path = $prefix === '' ? (string) $key : $prefix . '.' . $key;
        if (is_array($value)) flatten($value, $path);
        else echo $path, '=', var_export($value, true), "\n";
    }
}
flatten($config);

app.cache.driver='file'
app.debug=true
version='1'

Преимущество модели — полный контроль над путём. Цена — свой код стека, остановки и обработки разных источников.

<?php
$flat = new RecursiveIteratorIterator(
    new RecursiveArrayIterator(['app' => ['cache' => ['driver' => 'file'], 'debug' => true], 'version' => '1']),
    RecursiveIteratorIterator::LEAVES_ONLY
);
foreach ($flat as $key => $value) {
    $parts = [];
    for ($level = 0; $level < $flat->getDepth(); $level++) {
        $parts[] = (string) $flat->getSubIterator($level)->key();
    }
    $parts[] = (string) $key;
    echo implode('.', $parts), '=', var_export($value, true), "\n";
}

app.cache.driver='file'
app.debug=true
version='1'

Путь не появляется автоматически: пример собирает его из активных подытераторов. Это реальный стек текущей ветви, а не копия всего дерева.

<?php
$config = ['services' => ['cache' => 'redis', 'password' => 'secret']];
foreach ($config['services'] as $key => $value) {
    if (preg_match('/^(cache|timeout)$/', $key)) echo $key, '=', $value, "\n";
}

cache=redis

В дереве нельзя забыть родителя services, иначе рекурсивный фильтр не войдёт внутрь.

<?php
$source = new RecursiveArrayIterator([
    'services' => ['cache' => 'redis', 'timeout' => '30', 'password' => 'secret'],
]);
$filter = new RecursiveRegexIterator(
    $source,
    '/^(services|cache|timeout)$/',
    RecursiveRegexIterator::MATCH,
    RecursiveRegexIterator::USE_KEY
);
foreach (new RecursiveIteratorIterator($filter) as $key => $value) echo $key, '=', $value, "\n";

cache=redis
timeout=30

password не совпадает. Регулярное выражение выбирает строки, но не проверяет тип или допустимость самих значений.

<?php
$menu = ['shop' => ['catalog' => ['lamp' => '2'], 'cart' => '0'], 'status' => 'open'];
function draw(array $nodes, string $indent = ''): void {
    foreach ($nodes as $key => $value) {
        echo $indent, $key, is_array($value) ? '/' : '=' . $value, "\n";
        if (is_array($value)) draw($value, $indent . '  ');
    }
}
draw($menu);

shop/
  catalog/
    lamp=2
  cart=0
status=open

Линии здесь являются представлением. Они не изменяют ключи и не становятся частью исходных данных.

<?php
$tree = new RecursiveTreeIterator(
    new RecursiveArrayIterator(['shop' => ['catalog' => ['lamp' => '2'], 'cart' => '0'], 'status' => 'open']),
    RecursiveTreeIterator::BYPASS_KEY,
    CachingIterator::CATCH_GET_CHILD,
    RecursiveTreeIterator::LEAVES_ONLY
);
foreach ($tree as $key => $decorated) echo $key, ':', $decorated, "\n";

lamp:| | \-2
cart:| \-0
status:\-open

В LEAVES_ONLY выведены только значения-листья. Префикс объясняет положение, но не содержит имён родителей; путь собирают отдельно из ключей стека.

<?php
declare(strict_types=1);

$directory = new DirectoryIterator(__DIR__ . '/fixtures/catalog');
$rows = [];
$directory->rewind();
while ($directory->valid()) {
    if (!$directory->isDot()) {
        $entry = $directory->current();
        $filename = $entry->getFilename();
        $basename = $entry->getBasename();
        if ($filename !== $basename) {
            throw new RuntimeException('Unexpected basename');
        }
        $rows[] = [
            $filename,
            $entry->getExtension(),
            $entry->isDir() ? 'dir' : 'file',
        ];
    }
    $directory->next();
}
usort($rows, fn(array $left, array $right): int => $left[0] <=> $right[0]);
foreach ($rows as [$name, $extension, $type]) {
    echo $name, '|', $extension, '|', $type, "\n";
}

.env|env|file
README||file
photo.final.jpg|jpg|file
report.csv|csv|file
sub||dir

Конструктор открыл одну папку. На каждой допустимой позиции current() вернул тот же объект DirectoryIterator с данными текущей записи; getFilename()/getBasename()/getExtension() выделили части имени. У .env расширением считается env. Каталог sub виден как запись, но его содержимое не обходилось.

<?php
declare(strict_types=1);

$directory = new DirectoryIterator(__DIR__ . '/fixtures/dots');
$dotEntries = 0;
$ordinaryNames = [];
foreach ($directory as $entry) {
    if ($entry->isDot()) {
        $dotEntries++;
        continue;
    }
    $ordinaryNames[] = $entry->getFilename();
}
sort($ordinaryNames);
echo 'dotEntries=', $dotEntries, "\n";
echo 'ordinary=', implode(',', $ordinaryNames), "\n";

dotEntries=2
ordinary=.env,public.txt

isDot() вернул true только для записей . и ... Файл .env начинается с точки, но является обычной записью и не был потерян. Поэтому проверка имени на первый символ была бы ошибочной.

<?php
declare(strict_types=1);

$directory = new DirectoryIterator(__DIR__ . '/fixtures/one');
$filePosition = null;
foreach ($directory as $position => $entry) {
    if ($entry->getFilename() === 'only.txt') {
        $filePosition = $position;
        break;
    }
}
if (!is_int($filePosition)) {
    throw new RuntimeException('Fixture not found');
}
$directory->seek($filePosition);
$current = $directory->current();
echo 'keyIsInt=', is_int($directory->key()) ? 'yes' : 'no', "\n";
echo 'class=', $current::class, "\n";
echo 'sameObject=', $current === $directory ? 'yes' : 'no', "\n";
echo 'name=', (string) $current, "\n";
$directory->next();
echo 'afterFileValid=', $directory->valid() ? 'yes' : 'no', "\n";
$directory->rewind();
echo 'rewindIsDot=', $directory->isDot() ? 'yes' : 'no', "\n";

keyIsInt=yes
class=DirectoryIterator
sameObject=yes
name=only.txt
afterFileValid=no
rewindIsDot=yes

Сначала имя было найдено без предположения о позиции. seek() вернул тот же курсор к сохранённому целочисленному месту. current() не создал независимую копию: он вернул сам DirectoryIterator в состоянии only.txt. После next() valid() стал false; rewind() вернул позицию 0 — служебную точку.

<?php
declare(strict_types=1);

$flags = FilesystemIterator::KEY_AS_FILENAME
    | FilesystemIterator::CURRENT_AS_PATHNAME
    | FilesystemIterator::SKIP_DOTS;
$iterator = new FilesystemIterator(__DIR__ . '/fixtures/storage', $flags);
$rows = [];
foreach ($iterator as $key => $current) {
    $rows[] = $key . '|current=' . get_debug_type($current)
        . '|basename=' . basename($current);
}
sort($rows);
echo implode("\n", $rows), "\n";

.env|current=string|basename=.env
a.txt|current=string|basename=a.txt
b.log|current=string|basename=b.log
data|current=string|basename=data

KEY_AS_FILENAME сделал ключом только имя, CURRENT_AS_PATHNAME сделал текущим значением строку пути. Флаги из разных групп объединены оператором |; SKIP_DOTS убрал только . и ...

<?php
declare(strict_types=1);

$flags = FilesystemIterator::KEY_AS_FILENAME
    | FilesystemIterator::CURRENT_AS_FILEINFO
    | FilesystemIterator::SKIP_DOTS;
$iterator = new FilesystemIterator(__DIR__ . '/fixtures/files', $flags);
$rows = [];
foreach ($iterator as $name => $file) {
    if ($file->isFile()) {
        $rows[] = $name . '|class=' . $file::class . '|bytes=' . $file->getSize();
    }
}
sort($rows);
echo implode("\n", $rows), "\n";

a.txt|class=SplFileInfo|bytes=3
b.log|class=SplFileInfo|bytes=5

CURRENT_AS_FILEINFO вернул для каждой позиции SplFileInfo. Объект дал isFile() и getSize(); значение 0 этой константы проверяют сравнением маски режима, а не условием if ($flags & CURRENT_AS_FILEINFO).

<?php
declare(strict_types=1);

$initial = FilesystemIterator::KEY_AS_FILENAME
    | FilesystemIterator::CURRENT_AS_PATHNAME
    | FilesystemIterator::SKIP_DOTS;
$iterator = new FilesystemIterator(__DIR__ . '/fixtures/flags', $initial);
echo 'initialSkip=', ($iterator->getFlags() & FilesystemIterator::SKIP_DOTS) !== 0 ? 'yes' : 'no', "\n";

$iterator->setFlags(
    FilesystemIterator::KEY_AS_FILENAME
    | FilesystemIterator::CURRENT_AS_PATHNAME
);
echo 'afterReplaceSkip=', ($iterator->getFlags() & FilesystemIterator::SKIP_DOTS) !== 0 ? 'yes' : 'no', "\n";
$dotEntries = 0;
foreach ($iterator as $entry) {
    if ($iterator->isDot()) {
        $dotEntries++;
    }
}
echo 'dotEntries=', $dotEntries, "\n";

$iterator->setFlags(
    FilesystemIterator::KEY_AS_FILENAME
    | FilesystemIterator::CURRENT_AS_FILEINFO
    | FilesystemIterator::SKIP_DOTS
);
$mode = $iterator->getFlags() & FilesystemIterator::CURRENT_MODE_MASK;
echo 'fileInfoMode=', $mode === FilesystemIterator::CURRENT_AS_FILEINFO ? 'yes' : 'no', "\n";

initialSkip=yes
afterReplaceSkip=no
dotEntries=2
fileInfoMode=yes

Первый setFlags() получил новую полную маску без SKIP_DOTS, поэтому служебные точки вернулись. Второй вызов явно собрал все требуемые группы. CURRENT_AS_FILEINFO равен 0, поэтому текущий режим извлечён через CURRENT_MODE_MASK и проверен строгим равенством.

<?php
declare(strict_types=1);

$flags = FilesystemIterator::KEY_AS_FILENAME
    | FilesystemIterator::CURRENT_AS_FILEINFO
    | FilesystemIterator::SKIP_DOTS;
$iterator = new FilesystemIterator(__DIR__ . '/fixtures/hidden', $flags);
$names = [];
$dotEntries = 0;
$iterator->rewind();
while ($iterator->valid()) {
    $names[] = $iterator->key();
    $dotEntries += $iterator->isDot() ? 1 : 0;
    $iterator->next();
}
sort($names);
echo 'names=', implode(',', $names), "\n";
echo 'serviceDotEntries=', $dotEntries, "\n";

names=.env,public.txt
serviceDotEntries=0

SKIP_DOTS относится только к двум служебным записям. Он не является фильтром скрытых или начинающихся с точки файлов: .env остался в результате. Для отдельной политики скрытых файлов проверяйте имя самостоятельно.

<?php
declare(strict_types=1);

$pattern = __DIR__ . '/fixtures/uploads/*.jpg';
$iterator = new GlobIterator($pattern, FilesystemIterator::KEY_AS_FILENAME);
$names = [];
foreach ($iterator as $name => $file) {
    $names[] = $name;
}
sort($names);
echo 'matched=', $iterator->count(), "\n";
echo 'names=', implode(',', $names), "\n";
echo 'nestedIncluded=', in_array('deep.jpg', $names, true) ? 'yes' : 'no', "\n";

matched=2
names=hero.jpg,thumb.jpg
nestedIncluded=no

Шаблон *.jpg сопоставился с двумя именами одного уровня. count() вернул число совпавших путей. GlobIterator не выполняет рекурсивный поиск: sub/deep.jpg не попал в список.

<?php
declare(strict_types=1);

$pattern = __DIR__ . '/fixtures/backups/report-2026-??.csv';
$iterator = new GlobIterator($pattern, FilesystemIterator::KEY_AS_FILENAME);
$names = [];
foreach ($iterator as $name => $file) {
    $names[] = $name;
}
sort($names);
echo 'matched=', count($iterator), "\n";
echo implode("\n", $names), "\n";

matched=2
report-2026-01.csv
report-2026-10.csv

Каждый знак ? в glob-шаблоне соответствует одному символу имени. Поэтому два цифровых по факту имени совпали, а report-2026-final.csv и файл другого года — нет. Маска не проверяет, что символы являются цифрами; строгую проверку можно добавить после отбора.

<?php
declare(strict_types=1);

$iterator = new GlobIterator(
    __DIR__ . '/fixtures/documents/*.xml',
    FilesystemIterator::KEY_AS_FILENAME
);
$iterations = 0;
foreach ($iterator as $file) {
    $iterations++;
}
echo 'matched=', $iterator->count(), "\n";
echo 'iterations=', $iterations, "\n";

matched=0
iterations=0

Конструктор создал допустимый GlobIterator. count() вернул 0, foreach не выполнил тело ни разу. Отсутствующий каталог и пустой результат маски — разные состояния, их не следует объединять в одно сообщение.

<?php
declare(strict_types=1);

$path = __DIR__ . '/input/receipt.txt';
$file = new SplFileObject($path, 'rb');
$line = $file->fgets();

echo 'Первая строка: ' . rtrim($line, "\r\n") . "\n";

Первая строка: Заказ 42

$path хранит путь. new SplFileObject(...) открывает файл; rb означает чтение байтов без записи. Стрелка -> вызывает метод fgets() у этого объекта. Метод возвращает одну строку вместе с её переносом; rtrim убирает только CR/LF для аккуратной подписи. Полный текст при этом не загружается в массив.

<?php
declare(strict_types=1);

$payload = "Заказ 42\nКисть — 2 шт.\nИтого: 300 руб.\n";
$variants = [
    'сразу временный файл ОС' => new SplTempFileObject(0),
    'только память' => new SplTempFileObject(-1),
    'порог 16 байт' => new SplTempFileObject(16),
];

foreach ($variants as $label => $temp) {
    $written = $temp->fwrite($payload);
    if ($written !== strlen($payload)) {
        throw new RuntimeException('Неполная временная запись');
    }
    $temp->rewind();
    echo $label . ': ' . $temp->fstat()['size'] . ' байт; ' . trim($temp->fgets()) . "\n";
}

сразу временный файл ОС: 61 байт; Заказ 42
только память: 61 байт; Заказ 42
порог 16 байт: 61 байт; Заказ 42

0 просит использовать временный файл сразу, -1 запрещает перенос из памяти, 16 переносит данные после превышения 16 байт. Публичный API показывает размер и содержимое, но намеренно не обещает внутренний путь или измерение RAM. Во всех трёх случаях полезный контракт один: 61 байт записан и снова прочитан.

<?php
declare(strict_types=1);

$file = new SplFileObject(__DIR__ . '/input/catalog.csv', 'rb');
$file->setCsvControl(';', '"', '');
$header = $file->fgetcsv();
if ($header !== ['sku', 'name', 'price', 'stock']) {
    throw new RuntimeException('Неожиданные столбцы CSV');
}

$accepted = [];
$rejected = [];
while (($row = $file->fgetcsv()) !== false) {
    if ($row === [null]) { continue; }
    if (count($row) !== 4) {
        $rejected[] = 'строка ' . ($file->key() + 1) . ': нужно 4 поля';
        continue;
    }
    [$sku, $name, $price, $stock] = $row;
    if ($sku === '' || $name === '' || !is_numeric($price) || filter_var($stock, FILTER_VALIDATE_INT) === false || (int) $stock < 0) {
        $rejected[] = 'строка ' . ($file->key() + 1) . ': неверные данные';
        continue;
    }
    $accepted[$sku] = ['name' => $name, 'price' => (float) $price, 'stock' => (int) $stock];
}

foreach ($accepted as $sku => $item) {
    echo $sku . ': ' . $item['name'] . ', ' . number_format($item['price'], 2, '.', '') . ' руб., остаток ' . $item['stock'] . "\n";
}
foreach ($rejected as $message) { echo 'Ошибка: ' . $message . "\n"; }
echo 'Итог: принято ' . count($accepted) . ', отклонено ' . count($rejected) . ".\n";

BR-1: Кисть широкая, 150.00 руб., остаток 2
PN-9: Пена, 450.50 руб., остаток 0
Ошибка: строка 3: неверные данные
Ошибка: строка 5: нужно 4 поля
Итог: принято 2, отклонено 2.

CSV сначала проверяется по заголовку. Пустая физическая строка даёт [null] и пропускается явно. Затем проверяются число полей, обязательные значения, цена и целый неотрицательный остаток. Хорошие строки не теряются из-за соседней ошибки; плохие получают номер и причину. В реальном импорте после этой стадии начинают транзакцию БД и сохраняют только проверенную модель.

<?php
declare(strict_types=1);

$logPath = __DIR__ . '/orders.log';
$cursorPath = __DIR__ . '/orders.cursor';
file_put_contents($logPath, "order=41 status=paid\norder=42 status=new\n");
file_put_contents($cursorPath, "0");

$readNew = static function () use ($logPath, $cursorPath): void {
    $offset = (int) trim(file_get_contents($cursorPath));
    $log = new SplFileObject($logPath, 'rb');
    if ($log->fseek($offset, SEEK_SET) !== 0) {
        throw new RuntimeException('Смещение больше недоступно');
    }
    while (!$log->eof()) {
        $line = $log->fgets();
        if ($line === '') { break; }
        echo 'Новая запись: ' . rtrim($line, "\r\n") . "\n";
    }
    $next = $log->ftell();
    if ($next === false) { throw new RuntimeException('Не получена позиция'); }
    file_put_contents($cursorPath, (string) $next);
    echo 'Следующее смещение: ' . $next . "\n";
};

$readNew();
file_put_contents($logPath, "order=43 status=shipped\n", FILE_APPEND);
$readNew();

Новая запись: order=41 status=paid
Новая запись: order=42 status=new
Следующее смещение: 41
Новая запись: order=43 status=shipped
Следующее смещение: 65

ftell() возвращает байтовую позицию после полностью прочитанных строк. Она сохраняется отдельно; следующий запуск перед чтением вызывает fseek(). Это полезно для дописываемого журнала. В производстве также сохраняют identity файла и обрабатывают ротацию/усечение: если размер стал меньше курсора или inode изменился, чтение начинают по согласованной политике, а не с произвольного старого байта.

<?php
declare(strict_types=1);

$path = __DIR__ . '/measurements.txt';
$writer = new SplFileObject($path, 'wb');
for ($i = 1; $i <= 10000; $i++) {
    $line = $i . ';' . ($i % 10) . "\n";
    if ($writer->fwrite($line) !== strlen($line)) {
        throw new RuntimeException('Неполная запись строки ' . $i);
    }
}
$writer->fflush();
unset($writer);

$reader = new SplFileObject($path, 'rb');
$count = 0;
$sum = 0;
while (($line = $reader->fgets()) !== '') {
    [$id, $value] = explode(';', rtrim($line, "\r\n"), 2);
    $count++;
    $sum += (int) $value;
}
echo 'Строк: ' . $count . "\n";
echo 'Сумма значений: ' . $sum . "\n";
echo 'Размер файла: ' . filesize($path) . " байт\n";

Строк: 10000
Сумма значений: 45000
Размер файла: 68894 байт

Пример сам создаёт 10 000 строк, закрывает писателя и затем читает файл по одной строке. В памяти остаются текущая строка и два счётчика, а не массив из 10 000 записей. Это не обещание конкретного объёма RAM: интерпретатор и файловая система используют свои буферы. Видимый результат подтверждает число обработанных строк, сумму и точный размер созданного ASCII-файла.

<?php
declare(strict_types=1);

$file = new SplFileObject(__DIR__ . '/input/windows-utf8.txt', 'rb');
$number = 0;
while (!$file->eof()) {
    $line = $file->fgets();
    if ($line === '') { break; }
    $number++;
    if ($number === 1 && str_starts_with($line, "\xEF\xBB\xBF")) {
        $line = substr($line, 3);
    }
    echo $number . ': ' . rtrim($line, "\r\n") . "\n";
}

1: Заказ 42
2: Готов

Файл содержит UTF-8 BOM и переносы CRLF. SplFileObject возвращает байты как есть и не определяет кодировку. Только в первой строке проверяются три байта BOM; rtrim($line, "\r\n") удаляет оба варианта переноса, не стирая обычные пробелы текста. Для неизвестного внешнего ввода кодировку сначала проверяют, а преобразование выполняют явным инструментом вроде mb_convert_encoding/iconv с собственной политикой ошибок.