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

Сначала условия: когда эта тема вообще нужна

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

Это продвинутая глава. До неё нужны вызовы и return, замыкания, объекты и методы и исключения. Для обычной формы или последовательного скрипта Fiber не обязателен. Класс появился в PHP 8.1; примеры используют базовую функциональность, совместимую с PHP 8.2+.

Каждый пример запускается отдельно. Скачайте его архив, распакуйте целиком, откройте терминал в этом каталоге и выполните php example.php. Сравните вывод с блоком «Ожидаемый результат». Не объединяйте примеры в один файл: некоторые намеренно повторяют имена функций и классов.

Какая операция кому передаёт управление

$fiber = new Fiber(static function () { /* работа */ });
$request = $fiber->start();
$fiber->resume($answer);
$result = $fiber->getReturn();

Стрелка -> вызывает метод у конкретного объекта, двойное двоеточие :: здесь вызывает статический метод класса. start и resume возвращают значение следующего suspend либо null при завершении функции. По одному null нельзя строить весь протокол: suspend тоже может передать null; учитывайте состояние Fiber.

Минимальный обмен: запрос цены → 1200 → 2400

<?php
declare(strict_types=1);

$fiber = new Fiber(static function (): int {
    $unitPrice = Fiber::suspend('Нужна цена tea');
    if (!is_int($unitPrice) || $unitPrice < 0) {
        throw new InvalidArgumentException('Ожидалась цена в копейках');
    }
    return $unitPrice * 2;
});

echo $fiber->start(), "\n";
echo 'Приостановлен: ', $fiber->isSuspended() ? 'да' : 'нет', "\n";
$fiber->resume(1200);
echo 'Стоимость двух упаковок: ', $fiber->getReturn(), " коп.\n";

Нужна цена tea
Приостановлен: да
Стоимость двух упаковок: 2400 коп.

Пауза внутри обычной вложенной функции

<?php
declare(strict_types=1);

function readAvailableUnits(string $sku): int
{
    $response = Fiber::suspend(['operation' => 'stock', 'sku' => $sku]);
    if (!is_int($response) || $response < 0) {
        throw new UnexpectedValueException('Ожидался неотрицательный остаток');
    }
    return $response;
}

function stockLine(string $sku): string
{
    $units = readAvailableUnits($sku);
    return $sku . ': ' . $units . ' в наличии';
}

$fiber = new Fiber(static fn (): string => stockLine('tea'));
$request = $fiber->start();
$fixture = ['tea' => 4];
echo 'Запрос остатка: ', $request['sku'], "\n";
$fiber->resume($fixture[$request['sku']]);
echo $fiber->getReturn(), "\n";

Запрос остатка: tea
tea: 4 в наличии

В этом и отличие от простого «вернуть специальное значение»: не нужно вручную восстанавливать все промежуточные локальные переменные. Однако кто-то всё равно обязан получить ответ и вызвать resume. В примере это код после start; в асинхронной библиотеке — согласованный механизм выполнения задач.

Состояние важнее догадки «наверное, уже готово»

<?php
declare(strict_types=1);

$fiber = new Fiber(static function (): string {
    Fiber::suspend('жду');
    return 'готово';
});

try {
    $fiber->resume();
} catch (FiberError) {
    echo "До start: FiberError\n";
}
$fiber->start();
try {
    $fiber->getReturn();
} catch (FiberError) {
    echo "До завершения: FiberError\n";
}
$fiber->resume();
echo 'Итог: ', $fiber->getReturn(), "\n";
try {
    $fiber->resume();
} catch (FiberError) {
    echo "После завершения: FiberError\n";
}

До start: FiberError
До завершения: FiberError
Итог: готово
После завершения: FiberError

suspend вне выполняющегося Fiber вызывает FiberError. Исключение из задачи, которое не было перехвачено внутри, выходит через start или resume к управляющему коду. Продолжать завершённую задачу нельзя: создайте новый Fiber для новой работы, если протокол допускает повтор.

Почему это ещё не параллельность и не очередь заданий

Если внутри Fiber вызвать блокирующее чтение, HTTP-клиент или sleep, выполнение PHP будет ждать эту операцию. Fiber не переписывает её в неблокирующую. Для конкурентного ожидания нужны совместимые операции ввода-вывода и event loop — цикл, который отслеживает готовность событий и возобновляет нужные задачи. Выбор и настройка такой библиотеки выходят за рамки этого опыта.

Тяжёлый расчёт не ускорится от обёртки в Fiber: параллельные вычисления требуют другого решения, например отдельных процессов. Приостановленный Fiber также не является сохранённым заданием на завтра и не продолжает жить между независимыми HTTP-запросами. Надёжный фоновой импорт хранит состояние в очереди или базе.

Если нужно выдавать элементы по одному, начните с генератора и yield. Если нужна обычная функция расчёта — используйте её. Fiber оправдан, когда требуется именно управляемая пауза в стеке вызовов.

Самостоятельный опыт без настоящего ожидания

Попробуйте сами. В первом примере передайте в resume цену 900. Каким станет результат? Затем замените её строкой "900": где окажется ошибка?