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

Выдавать товары по одному, когда их просит foreach

Каталог может состоять из большого файла или многих страниц API. Хотим обрабатывать следующую запись, не собирая весь каталог заранее. Генератор — функция, которая приостанавливается на yield и выдаёт очередное значение.

Что получится. Цикл получит Чай, затем Кофе. По сообщениям будет видно, когда выполняется каждая часть функции.

<?php
declare(strict_types=1);

function products(): Generator
{
    echo "Готовим Чай\n";
    yield 'Чай';
    echo "Готовим Кофе\n";
    yield 'Кофе';
}
$products = products();
echo "Начинаем каталог\n";
foreach ($products as $title) {
    echo 'Показали: ', $title, "\n";
}

Начинаем каталог
Готовим Чай
Показали: Чай
Готовим Кофе
Показали: Кофе

Экономия возникает, когда источник тоже читается постепенно

Если сначала file_get_contents загрузит гигантский файл целиком, yield не отменит эту затрату. Если источник — API, держите разумную страницу данных, выдавайте её записи, затем запрашивайте следующую. Генератор не даёт произвольный доступ по индексу; для маленького списка, который нужно сортировать и обходить многократно, массив может быть удобнее.

Прочитать подготовленный файл строка за строкой

<?php
declare(strict_types=1);

function productLines(string $path): Generator
{
    $handle = fopen($path, 'r');
    if ($handle === false) { throw new RuntimeException('Каталог недоступен'); }
    try {
        while (($line = fgets($handle)) !== false) {
            $title = trim($line);
            if ($title !== '') { yield $title; }
        }
    } finally {
        fclose($handle);
    }
}
foreach (productLines(__DIR__ . '/products.txt') as $title) {
    echo 'Товар: ', $title, "\n";
}

Товар: Чай
Товар: Кофе

Для повторного прохода создавать новый итератор

<?php
declare(strict_types=1);

class Catalog implements IteratorAggregate
{
    public function getIterator(): Traversable
    {
        yield 'Чай';
        yield 'Кофе';
    }
}
$catalog = new Catalog();
foreach ($catalog as $title) { echo 'Список: ', $title, "\n"; }
foreach ($catalog as $title) { echo 'Этикетка: ', $title, "\n"; }

Список: Чай
Список: Кофе
Этикетка: Чай
Этикетка: Кофе

Структура данных выбирается по операции

<?php
declare(strict_types=1);

$queue = new SplQueue();
$queue->enqueue('Заказ 42 принят');
$queue->enqueue('Заказ 43 принят');
while (!$queue->isEmpty()) {
    echo 'Отправить: ', $queue->dequeue(), "\n";
}

Отправить: Заказ 42 принят
Отправить: Заказ 43 принят

SPL предоставляет также стеки, кучи, итераторы каталогов и обёртки фильтрации. Генератор описывает последовательное вычисление, а очередь хранит ожидающие элементы. Это разные задачи; стоимость операций оценивайте для выбранной структуры и объёма.

Ошибка источника возникает в момент потребления

<?php
declare(strict_types=1);

function importedTitles(): Generator
{
    yield 'Чай';
    throw new RuntimeException('Вторая страница каталога недоступна');
}
$titles = importedTitles();
try {
    foreach ($titles as $title) { echo 'Получен: ', $title, "\n"; }
} catch (RuntimeException $error) {
    echo 'Импорт не завершён: ', $error->getMessage(), "\n";
}

Получен: Чай
Импорт не завершён: Вторая страница каталога недоступна

Ранний break останавливает потребителя, но сохранённый объект генератора может удерживать открытый ресурс. Освобождайте ссылки или задавайте явный жизненный цикл обёрткой. Преобразование iterator_to_array материализует результат и может вернуть прежнюю проблему памяти.

Fiber приостанавливает стек, но не ускоряет блокирующую сеть

Генератор естественно выдаёт последовательность. Fiber нужен, когда приостановить и продолжить требуется цепочку обычных вызовов. Он не является отдельным потоком ОС и сам не создаёт event loop. Блокирующий HTTP-запрос внутри Fiber останется блокирующим без подходящего неблокирующего транспорта и планировщика.

Сначала закончите последовательный импорт. Затем отдельный маршрут Fiber покажет start, suspend, resume, результат и ошибки состояния на точных шагах.

Попробуйте. Добавьте к Catalog третий товар Сахар. Останутся ли два прохода независимыми?

Дальше: полный договор языка и специальные случаи

Далее сохранены ключи yield, yield from, getReturn, send/throw, ссылки и полный Iterator-протокол. Это разные стороны управления потоком; каждый специальный шаг опирается на наблюдаемую паузу первого примера.

Разделы ниже сохраняют специальные правила официального PHP Manual: Обычный foreach по объекту перебирает доступные свойства, Генератор выдаёт ключи, но сборка массива может перезаписать запись, Элементы потока и итог работы: yield from и getReturn, Send и throw: передать ответ в приостановленный генератор, Генератор по ссылке: когда потребитель действительно меняет источник, Пять методов Iterator: как foreach получает очередную запись, Yield без значения: элемент null ещё не означает конец, Исключение проходит через yield from к приостановленному шагу.

Обычный foreach по объекту перебирает доступные свойства

Разработчик передал в foreach объект клиента и ожидал список заявок. Но объект без Iterator/IteratorAggregate не превращается в результат API. По умолчанию PHP перечисляет доступные из текущей области свойства. Это следует отличать от собственной коллекции.

<?php
declare(strict_types=1);

class CatalogCard
{
    public string $title = 'Чай';
    protected string $warehouse = 'Склад A';
    private string $internalNote = 'Учебная заметка';

    public function visibleNamesInside(): array
    {
        $names = [];
        foreach ($this as $name => $value) {
            $names[] = $name;
        }
        return $names;
    }
}

$card = new CatalogCard();
foreach ($card as $name => $value) {
    echo $name, ': ', $value, "\n";
}
echo implode(', ', $card->visibleNamesInside()), "\n";

title: Чай
title, warehouse, internalNote

Для публичного API перечисляйте поля явно или используйте JsonSerializable с определённым договором. Добавление нового public-поля иначе может незаметно поменять экспорт. Для обхода списка товаров создайте коллекцию с IteratorAggregate или перебирайте массив, полученный listMethod; foreach по самому API-клиенту не вызывает сеть.

Генератор выдаёт ключи, но сборка массива может перезаписать запись

Интеграция получила две страницы товаров. Каждая страница локально пронумерована от нуля. Если делегировать их через yield from, цикл увидит все товары, однако массив с повторными ключами вместит только последнее значение каждого ключа. Перед этим разберите первый yield и ключи массива.

Запись yield $key => $value выдаёт пару ключ/значение. Yield from $items делегирует перебор другому массиву или Traversable: это не автоматическая перенумерация. Сохранение всех значений или исходных ключей — отдельное решение вызывающего кода.

<?php
declare(strict_types=1);

function catalogPages(): Generator
{
    yield from [0 => 'Чай', 1 => 'Кофе'];
    yield from [0 => 'Сок', 1 => 'Вода'];
}

$seen = [];
foreach (catalogPages() as $key => $title) {
    $seen[] = $key . ':' . $title;
}
echo implode(', ', $seen), "\n";
echo implode(', ', iterator_to_array(catalogPages())), "\n";
echo implode(', ', iterator_to_array(catalogPages(), false)), "\n";

0:Чай, 1:Кофе, 0:Сок, 1:Вода
Сок, Вода
Чай, Кофе, Сок, Вода

Если ключ — настоящий ID, повторение может означать дублирование страниц или изменение данных во время обхода. Тогда нельзя молча выбросить проблему через false: проверьте ID и выберите политику конфликтов. Для экспорта без хранения всего результата foreach может сразу записывать строки в файл.

Yield без выражения выдаёт null. Автоматические числовые ключи удобны для последовательности, но при явных ключах и yield from не полагайтесь на глобальную уникальность. Генератор уменьшает память только пока потребитель не собирает все элементы обратно в большой массив.

Элементы потока и итог работы: yield from и getReturn

Экспорт отдаёт строки по одной, а после завершения хочет вернуть число обработанных записей. Обычный return не станет ещё одной строкой. Он завершит генератор и сохранит отдельный итог, доступный через getReturn.

<?php
declare(strict_types=1);

function exportBatch(): Generator
{
    yield 'ID;TITLE';
    yield '42;Чай';
    return 1;
}

function exportDocument(): Generator
{
    $written = yield from exportBatch();
    return ['rows' => $written];
}

$export = exportDocument();
foreach ($export as $line) {
    echo $line, "\n";
}
echo 'Записей: ', $export->getReturn()['rows'], "\n";

ID;TITLE
42;Чай
Записей: 1

Yield from можно делегировать массиву, Iterator или другому генератору. Полезный return в этом опыте принадлежит именно генератору. Если обход прервали или внутри возникла необработанная ошибка, не объявляйте экспорт успешным только потому, что часть строк уже получена.

В реальном файле выбирайте временный путь и завершайте публикацию результата только после успешного полного обхода и закрытия ресурса. Генератор не предоставляет транзакцию сам: уже записанные строки остаются внешним эффектом. Return/getReturn и yield from поддерживаются с PHP 7.0, поэтому доступны в базовой версии этого руководства.

Send и throw: передать ответ в приостановленный генератор

Обычно foreach только получает очередное значение. Иногда нужен управляемый диалог: вычислитель запросил количество, вызывающий код передал его и получил итог. Это расширенный протокол генератора, а не обязательный способ обрабатывать форму; обычная функция с параметром будет проще, если пауз нет.

<?php
declare(strict_types=1);

function quoteDialog(): Generator
{
    $quantity = yield 'Нужно количество';
    if (!is_int($quantity) || $quantity < 1 || $quantity > 10) {
        throw new InvalidArgumentException('Ожидалось количество от 1 до 10');
    }
    return 120 * $quantity;
}

$dialog = quoteDialog();
echo $dialog->current(), "\n";
$dialog->send(3);
echo 'Итого: ', $dialog->getReturn(), "\n";

Нужно количество
Итого: 360

<?php
declare(strict_types=1);

function previewDialog(): Generator
{
    try {
        yield 'Черновик готов';
        return 'Подтверждён';
    } catch (RuntimeException $error) {
        return 'Отменён';
    } finally {
        echo "Локальный буфер освобождён\n";
    }
}

$dialog = previewDialog();
echo $dialog->current(), "\n";
$dialog->throw(new RuntimeException('Учебная отмена'));
echo $dialog->getReturn(), "\n";

Черновик готов
Локальный буфер освобождён
Отменён

Send умеет сам начать ещё не запущенный генератор, но явный current в учебном протоколе делает точку паузы видимой. Не смешивайте произвольные next/send/foreach, не определив, кто владеет продвижением: легко пропустить шаг.

Это синхронные примеры без сети, потоков и параллельной работы. Возможность приостановиться сама по себе не делает HTTP асинхронным. Для приложения нужны договор сообщений, владение ресурсами и обработка отмены; иногда для такой задачи подходит Fiber или библиотека цикла событий, а иногда достаточно обычной функции.

Генератор по ссылке: когда потребитель действительно меняет источник

Обычно цикл по генератору получает значения. Если инструмент нормализации должен менять элементы уже существующего небольшого массива, можно намеренно вернуть ссылки. Это отдельный, более тесный договор владения: изменение в потребителе затронет источник.

<?php
declare(strict_types=1);

function &stockValues(array &$stock): Generator
{
    foreach ($stock as &$quantity) {
        yield $quantity;
    }
    unset($quantity);
}

$stock = ['tea' => 2, 'coffee' => -1];
foreach (stockValues($stock) as &$quantity) {
    if ($quantity < 0) {
        $quantity = 0;
    }
}
unset($quantity);
echo $stock['tea'], ', ', $stock['coffee'], "\n";

2, 0

Обнуление отрицательного остатка здесь — видимое правило учебной нормализации, а не универсально правильная политика склада. В реальном импорте отрицательное число может быть ошибкой, которую нужно сохранить в отчёт и отклонить строку.

Генератор по ссылке не экономит память исходного массива: он уже существует. Чаще проще вернуть нормализованное значение отдельной функцией или явно изменить массив обычным foreach. Выбирайте ссылочный протокол лишь там, где вызывающий код понимает, что источник будет изменён; не применяйте его к общему read-only контракту коллекции.

Пять методов Iterator: как foreach получает очередную запись

Генератор скрывает позицию обхода внутри PHP. Если коллекция сама должна управлять курсором, можно явно выполнить интерфейс Iterator. Для понимания сначала возьмём два названия из обычного массива. Это больше кода, чем yield, зато каждый шаг foreach становится видимым.

Implements Iterator обещает пять методов. Rewind ставит начало; valid сообщает, существует ли текущая позиция; current отдаёт значение; key — его ключ; next передвигает позицию. Возвращаемые типы mixed у current/key разрешают разные виды данных, но наш договор выдаёт строковые названия и числовые позиции.

<?php
declare(strict_types=1);

class TitleCursor implements Iterator
{
    private int $position = 0;

    public function __construct(private array $titles) {}

    public function rewind(): void { $this->position = 0; }
    public function valid(): bool { return array_key_exists($this->position, $this->titles); }
    public function current(): mixed { return $this->titles[$this->position]; }
    public function key(): mixed { return $this->position; }
    public function next(): void { $this->position++; }
}

$cursor = new TitleCursor(['Чай', 'Кофе']);
foreach ($cursor as $position => $title) {
    echo $position, ': ', $title, "\n";
}
$cursor->rewind();
echo 'После rewind: ', $cursor->current(), "\n";

0: Чай
1: Кофе
После rewind: Чай

Если два вложенных цикла используют этот же объект TitleCursor, они меняют одну position и мешают друг другу. IteratorAggregate с новым Iterator при каждом getIterator отделяет курсоры от самой коллекции. Именно это часто удобно для коллекции заказов, которую нужно обходить несколько раз.

Генератор нельзя произвольно перемотать после продвижения; вместо этого обычно создают новый вызовом функции. Iterator может поддерживать rewind, но сам обязан реализовать его честно: сетевой поток или файл не всегда безопасно начинать заново. Не обещайте повторяемость лишь по наличию интерфейса.

Для обычного массива не нужно писать свой Iterator: foreach уже работает. Он полезен, когда в проекте действительно есть отдельный протокол курсора, доступ к источнику по страницам или адаптация чужой коллекции. Выбирать между yield, IteratorAggregate и Iterator следует по владению состоянием и повторным обходам, а не по представлению, что более длинный класс всегда профессиональнее.

Yield без значения: элемент null ещё не означает конец

В потоковом обработчике пустой результат иногда допустим: например, шаг подготовки пока не выдал строку. Yield без выражения создаёт элемент null с очередным числовым ключом. Это реальная остановка генератора, а не return и не пропуск элемента.

После первого генератора разделим два вопроса: current возвращает текущее значение, valid отвечает, есть ли текущий элемент вообще. Если проверять только current !== null, обработчик потеряет законные null-элементы.

<?php
declare(strict_types=1);

function preparationSteps(): Generator
{
    yield;
    yield 'Отчёт подготовлен';
}

$steps = preparationSteps();
while ($steps->valid()) {
    $value = $steps->current();
    echo $steps->key(), ': ', $value === null ? '(нет значения)' : $value, "\n";
    $steps->next();
}
echo $steps->valid() ? "Есть элемент\n" : "Генератор завершён\n";
echo $steps->current() === null ? "Current после конца: null\n" : "Есть значение\n";

0: (нет значения)
1: Отчёт подготовлен
Генератор завершён
Current после конца: null

Для передачи понятных событий пользователю лучше явные значения вроде массива с type=prepared или отдельного enum. Null уместен там, где его значение уже согласовано между генератором и потребителем. Упражнение: замените первый yield на return. Решение: ни первого, ни второго элемента не будет, потому что return завершит выполнение до второго yield.

Исключение проходит через yield from к приостановленному шагу

Импорт делится на этапы: внешняя функция организует процесс, внутренняя выдаёт очередную запись. Yield from делегирует не только значения: исключение, переданное внешнему генератору, попадает в текущую точку yield внутреннего. Это полезно для управляемой отмены, если ваш обработчик действительно использует такой протокол.

Внутренний finally завершает свой участок, а внешний catch решает, что сообщить вызывающему коду. До этого опыта нужны send и throw и обычный try/finally. Для простого обхода CSV достаточно foreach и обычной обработки исключения.

<?php
declare(strict_types=1);

function importRows(array &$events): Generator
{
    try {
        yield 'Строка P-42';
        yield 'Строка P-43';
    } finally {
        $events[] = 'Внутренний этап закрыт';
    }
}

function runImport(array &$events): Generator
{
    try {
        yield from importRows($events);
    } catch (RuntimeException $error) {
        $events[] = 'Внешний этап обработал отмену';
        yield 'Импорт отменён';
    }
    return 'Завершено';
}

$events = [];
$job = runImport($events);
echo $job->current(), "\n";
echo $job->throw(new RuntimeException('Остановить импорт')), "\n";
$job->next();
echo $job->getReturn(), "\n";
echo implode(' / ', $events), "\n";

Строка P-42
Импорт отменён
Завершено
Внутренний этап закрыт / Внешний этап обработал отмену

При yield from из массива нет внутренней PHP-функции с try/catch: исключение обрабатывается во внешнем генераторе. Send в делегирующей цепочке генераторов тоже передаётся к текущему внутреннему yield. Уже закрытому генератору throw не создаёт новую жизнь: исключение выбрасывается в контексте вызывающего кода.

Упражнение: перенесите catch внутрь importRows и выдайте там «Строка пропущена». Решение: внутренний генератор сам решит, продолжать ли следующие строки; внешний catch не сработает для уже обработанного исключения. Место catch задаёт границу восстановления.