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

<?php
function skus() { yield 'A-10'; yield 'B-20'; }
$items = skus();
echo $items->current(), "\n", $items->current(), "\n";
$items->next();
echo $items->current(), "\n";

A-10
A-10
B-20

current — чтение позиции, next — её смена. Полезно сначала проверить товар, затем решать, принимать его или завершать импорт.

<?php
function readings() { yield null; }
$rows = readings();
echo $rows->valid() ? "Строка есть\n" : "Строк нет\n";
var_dump($rows->current());
$rows->next();
echo $rows->valid() ? "Строка есть\n" : "Строк нет\n";
var_dump($rows->current());

Строка есть
NULL
Строк нет
NULL

В двух состояниях current() даёт null, но valid() различает их. Нельзя использовать истинность текущего значения как условие обхода: 0, пустая строка и false тоже могут быть данными.

<?php
function priceFeed() { yield 'A-10' => 900; }
$feed = priceFeed();
echo $feed->key(), ': ', $feed->current(), "\n";

A-10: 900

Метод key() тоже способен запустить ещё не начатое тело. key() читает ключ Generator; функция key($array) относится к внутреннему указателю массива и имеет другой объект работы.

<?php
function updates() { yield 'A-10' => 900; yield 'A-10' => 950; }
$feed = updates();
while ($feed->valid()) {
    echo $feed->key(), ': ', $feed->current(), "\n";
    $feed->next();
}

A-10: 900
A-10: 950

Поток событий изменения цены хранит оба события в порядке. Это не словарь текущих цен. Если нужен только последний снимок, присваивайте по ключу осознанно; если история — сохраняйте список записей.

<?php
declare(strict_types=1);

function orders(): Generator { yield 'A-42'; yield 'A-43'; }
$orders = orders();
echo 'Подготовить: ', $orders->current(), "\n";
$orders->next();
echo 'Подготовить: ', $orders->current(), "\n";
$orders->next();
echo $orders->valid() ? "Остались заказы\n" : "Все заказы выданы\n";

Подготовить: A-42
Подготовить: A-43
Все заказы выданы

current читает текущую запись, next продолжает после её yield. После второго next источник завершён и valid отвечает false. Сам next ничего не возвращает: полезный результат читается отдельно. Для обычной обработки foreach выполняет эти шаги за вас.

<?php
function orders() { yield 41; yield 52; }
$orders = orders();
$orders->next();
echo $orders->current(), "\n";

52

Для обычного полного обхода проще foreach. При собственном цикле начните с valid()/current()/rewind(), а next ставьте после обработки.

<?php
function requests() { echo "Подготовка\n"; yield 41; yield 52; }
$requests = requests();
$requests->rewind();
$requests->rewind();
echo $requests->current(), "\n";

Подготовка
41

Повторное rewind на первом yield не выполняет тело с начала. Это позволяет foreach начать работу с уже проверенным первым элементом.

<?php
function orders() { yield 41; yield 52; }
$orders = orders();
$orders->rewind();
$orders->next();
try { $orders->rewind(); }
catch (Exception $error) { echo "Создайте новый обход\n"; }
foreach (orders() as $id) { echo $id, "\n"; }

Создайте новый обход
41
52

Новая функция orders() — новый генератор. Для живого API это также новый запрос и потенциально другой снимок данных; повторяемость источника нужно проектировать отдельно.

<?php
function exportedOrders() { yield 41; yield 52; return 2; }
$orders = exportedOrders();
foreach ($orders as $id) { echo 'Заказ ', $id, "\n"; }
echo 'Выгружено: ', $orders->getReturn(), "\n";

Заказ 41
Заказ 52
Выгружено: 2

Читатель получает два заказа; итог 2 доступен отдельно, когда генератор дошёл до return. Не храните return в том же списке, что и заказы.

<?php
function job() { yield 'обработать'; return 'готово'; }
$job = job();
try { $job->getReturn(); }
catch (Exception $error) { echo "Итог ещё не готов\n"; }
foreach ($job as $step) { echo $step, "\n"; }
echo $job->getReturn(), "\n";

Итог ещё не готов
обработать
готово

Проверка valid() false сама по себе не доказывает успешный return после ошибки. Исключения задачи обрабатывают в момент исполнения, а успех фиксируют отдельно.

<?php
declare(strict_types=1);

function quote(): Generator
{
    $quantity = yield 'Сколько упаковок чая нужно?';
    if (!is_int($quantity) || $quantity < 1) { throw new InvalidArgumentException('Нужно положительное целое количество'); }
    yield 'Предложение: ' . ($quantity * 25900) . ' коп.';
}
$quote = quote();
echo $quote->current(), "\n";
echo $quote->send(2), "\n";

Сколько упаковок чая нужно?
Предложение: 51800 коп.

Строка выходит наружу через yield. send(2) продолжает функцию и делает 2 результатом этого yield внутри: $quantity получает 2. Следующее выданное значение возвращается из send. Так устроен двусторонний обмен; обычной однократной калькуляции достаточно функции с параметром.

<?php
function reservation() {
    $stock = yield ['sku' => 'A-10'];
    if (!is_int($stock) || $stock < 0) { throw new InvalidArgumentException('Некорректный остаток'); }
    return $stock >= 2 ? 'Можно резервировать' : 'Недостаточно';
}
$task = reservation();
$request = $task->current();
echo 'Проверяем ', $request['sku'], "\n";
$next = $task->send(5);
echo $next === null && !$task->valid() ? "Других запросов нет\n" : "Нужны дополнительные данные\n";
echo $task->getReturn(), "\n";

Проверяем A-10
Других запросов нет
Можно резервировать

send возвращает следующее yield, а окончательный return — отдельный getReturn. Здесь источник завершился сразу после решения. Проверка valid отличает конец от законного yield null.

<?php
function shipping() {
    try { yield 'Запросить доставку'; }
    catch (RuntimeException $error) { yield 'Ручная проверка'; }
}
$task = shipping();
echo $task->current(), "\n";
echo $task->throw(new RuntimeException('Сервис недоступен')), "\n";

Запросить доставку
Ручная проверка

Сбой не превращается в нулевую цену. Здесь catch предлагает другой явно названный процесс. После второго yield задача ещё приостановлена; следующий next завершит её.

<?php
function done() { if (false) { yield; } }
$task = done();
$task->valid();
try { $task->throw(new RuntimeException('Поздний ответ')); }
catch (RuntimeException $error) { echo $error->getMessage(), "\n"; }

Поздний ответ

После окончания тела точек ожидания нет. Снаружи нужен контроль жизненного цикла задач; поздний сетевой ответ нельзя отправлять в уже завершённую работу.

<?php
function stocks() { yield 0; yield 4; }
$stocks = stocks();
while ($stocks->valid()) {
    echo 'Остаток: ', $stocks->current(), "\n";
    $stocks->next();
}

Остаток: 0
Остаток: 4

Условие while ($stocks->current()) остановилось бы на нуле. valid проверяет состояние обхода, а не истинность значения.

<?php
declare(strict_types=1);

function batch(): Generator { echo "Открыли каталог\n"; yield 'Чай'; }
$batch = batch();
echo "Создан отложенный обход\n";
echo $batch->valid() ? "Первый товар доступен\n" : "Каталог пуст\n";
echo $batch->valid() ? "Тот же товар всё ещё доступен\n" : "Каталог пуст\n";
echo $batch->current(), "\n";

Создан отложенный обход
Открыли каталог
Первый товар доступен
Тот же товар всё ещё доступен
Чай

Первый valid продвигает незапущенный генератор до первого yield. Второй valid не переходит к следующему товару и не повторяет открытие источника. Учитывайте этот побочный эффект, если функция внутри читает файл или выполняет запрос.

<?php
function orders() { yield 41; }
$orders = orders();
try { serialize($orders); }
catch (Exception $error) { echo "Генератор не сериализуется\n"; }
echo method_exists($orders, '__wakeup') ? "У этой версии есть исторический метод\n" : "Исторический __wakeup в текущей версии отсутствует\n";

Генератор не сериализуется
Исторический __wakeup в текущей версии отсутствует

Сериализация активного стека генератора запрещена. Карточка сохраняет историческое имя из полного Manual и явно отделяет его от текущего API. Следующий практический пример сохраняет after_id в JSON и создаёт новый обход.

<?php
function ordersAfter(int $lastId): Generator {
    foreach ([41, 52, 63] as $id) { if ($id > $lastId) { yield $id; } }
}
$checkpoint = json_encode(['after_id' => 41], JSON_THROW_ON_ERROR);
$state = json_decode($checkpoint, true, flags: JSON_THROW_ON_ERROR);
foreach (ordersAfter($state['after_id']) as $id) { echo $id, "\n"; }

52
63

JSON здесь создан той же программой; при чтении из внешнего хранилища проверяют схему и тип after_id. В реальном импорте надёжный checkpoint записывают после подтверждения обработки; нужны порядок источника и защита от повторного эффекта, а не только номер.