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

<?php
declare(strict_types=1);

$task = new Fiber(function () { echo "Рассчитываем доставку\n"; });
echo "Задача добавлена в список\n";
echo $task->isStarted() ? "Уже выполнялась\n" : "Расчёт ещё не начался\n";
$task->start();

Задача добавлена в список
Расчёт ещё не начался
Рассчитываем доставку

Конструктор Fiber получает callable, но не запускает его. Это позволяет собрать список задач до первого выполнения. Тело начинает start, как видно по последней строке.

<?php
function makeLabel(string $sku): string { return 'Товар ' . $sku; }
$task = new Fiber('makeLabel');
$task->start('A-10');
echo $task->getReturn(), "\n";

Товар A-10

Строка makeLabel указывает на заранее объявленную функцию; не принимайте произвольное имя обработчика от посетителя. Эта простая функция не приостанавливается: для неё обычный makeLabel("A-10") практичнее. Пример показывает допустимый callable, а не пользу оборачивания любого вызова в Fiber.

<?php
$task = new Fiber(function ($orderId) { Fiber::suspend('Проверить ' . $orderId); });
echo $task->start(41), "\n";
$task->resume();

Проверить 41

start передаёт вход callback. Сам номер заказа не обязан храниться в глобальной переменной: он принадлежит конкретному запуску задачи.

<?php
$task = new Fiber(function () { return 'готово'; });
var_dump($task->start());
echo $task->getReturn(), "\n";
try { $task->start(); }
catch (FiberError $error) { echo "Нужен новый Fiber\n"; }

NULL
готово
Нужен новый Fiber

Для новой независимой обработки создайте новый объект. Даже если первый callback сразу завершился без suspend, этот Fiber уже использован.

<?php
declare(strict_types=1);

$task = new Fiber(function () {
    $priceKopecks = Fiber::suspend('Нужна цена упаковки чая');
    return $priceKopecks * 2;
});
echo $task->start(), "\n";
$task->resume(25900);
echo 'Две упаковки: ', $task->getReturn(), " коп.\n";

Нужна цена упаковки чая
Две упаковки: 51800 коп.

resume передаёт 25900 в приостановленный suspend как его результат. Код после паузы использует полученную цену. Окончательная сумма находится в getReturn; учебный ответ передан локально, сеть не выполнялась.

<?php
$task = new Fiber(function () { Fiber::suspend(); });
try { $task->resume(); }
catch (FiberError $error) { echo "Сначала start\n"; }
$task->start();
if ($task->isSuspended()) { $task->resume(); }
echo $task->isTerminated() ? "Готово\n" : "Ждёт\n";

Сначала start
Готово

Проверка isSuspended пригодна управляющему коду. Она не заменяет обработку ошибок самого callback.

<?php
$task = new Fiber(function () {
    try { Fiber::suspend('Запросить цену'); }
    catch (RuntimeException $error) { Fiber::suspend('Проверить вручную'); }
});
echo $task->start(), "\n";
echo $task->throw(new RuntimeException('Тайм-аут')), "\n";
$task->resume();

Запросить цену
Проверить вручную

catch может создать новый этап ожидания. Поэтому после throw задача не обязательно завершена — это определяется тем, что сделало тело.

<?php
$task = new Fiber(function () { Fiber::suspend(); });
$task->start();
try { $task->throw(new RuntimeException('Доставка недоступна')); }
catch (RuntimeException $error) { echo $error->getMessage(), "\n"; }
var_dump($task->isTerminated());
try { $task->getReturn(); }
catch (FiberError $error) { echo "Успешного результата нет\n"; }

Доставка недоступна
bool(true)
Успешного результата нет

Отмена и ошибка не являются обычным return. Не пытайтесь считать getReturn успешным только по isTerminated().

<?php
$task = new Fiber(function () { return 900 + 300; });
var_dump($task->start());
echo 'Итого: ', $task->getReturn(), "\n";
echo 'Повторное чтение: ', $task->getReturn(), "\n";

NULL
Итого: 1200
Повторное чтение: 1200

Повторное чтение не запускает расчёт снова. В этом примере Fiber избыточен для сложения; в составной задаче итог получают тем же методом после последнего ответа.

<?php
$task = new Fiber(function () { $stock = Fiber::suspend(); return $stock > 0; });
$task->start();
try { $task->getReturn(); }
catch (FiberError $error) { echo "Ещё ждём остаток\n"; }
$task->resume(5);
echo $task->getReturn() ? "Можно показать кнопку заказа\n" : "Товар закончился\n";

Ещё ждём остаток
Можно показать кнопку заказа

До resume решение не вычислено, getReturn даёт FiberError. Ответ 5 позволяет вернуть true и включить действие интерфейса. Булево значение полезно как решение, но не объясняет ошибки сети — их надо обрабатывать отдельно.

<?php
declare(strict_types=1);

$task = new Fiber(function () { return 'Смета доставки: 300 руб.'; });
echo $task->isStarted() ? "Уже запускалась\n" : "Задача новая\n";
$task->start();
echo $task->getReturn(), "\n";
echo $task->isStarted() ? "Повторный start запрещён\n" : "Можно запустить\n";
echo $task->isTerminated() ? "Для нового расчёта создайте новый Fiber\n" : "Расчёт продолжается\n";

Задача новая
Смета доставки: 300 руб.
Повторный start запрещён
Для нового расчёта создайте новый Fiber

isStarted остаётся true после завершения и не означает «выполняется прямо сейчас». isTerminated сообщает конец. Чтобы пересчитать другой заказ, создают другой Fiber; готовый результат первого можно читать повторно.

<?php
$tasks = [new Fiber(function () { echo "Проверка склада\n"; })];
foreach ([1, 2] as $pass) {
    foreach ($tasks as $task) { if (!$task->isStarted()) { $task->start(); } }
}

Проверка склада

Второй проход управляющего кода не выполняет повторный start. Для перезапуска самой проверки понадобится новый Fiber, а не изменение флага.

<?php
declare(strict_types=1);

$task = new Fiber(function () { return Fiber::suspend('Нужно расстояние'); });
echo $task->isSuspended() ? "Ждёт ответ\n" : "Ожидание ещё не началось\n";
echo $task->start(), "\n";
echo $task->isSuspended() ? "Можно передать расстояние\n" : "Ответ сейчас не нужен\n";
$task->resume(15);
echo $task->isSuspended() ? "Ждёт дальше\n" : "Ожидание закончено\n";
echo 'Получено: ', $task->getReturn(), " км\n";

Ожидание ещё не началось
Нужно расстояние
Можно передать расстояние
Ожидание закончено
Получено: 15 км

Созданный Fiber ещё не приостановлен. После suspend он принимает resume/throw, после завершения — уже нет. Поздний ответ нужно сверять с состоянием, а не отправлять в любой сохранённый объект задачи.

<?php
$task = new Fiber(function () { return Fiber::suspend(); });
$task->start();
foreach ([5, 6] as $reply) {
    if ($task->isSuspended()) { $task->resume($reply); }
    else { echo "Повторный ответ пропущен\n"; }
}
echo 'Результат: ', $task->getReturn(), "\n";

Повторный ответ пропущен
Результат: 5

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

<?php
declare(strict_types=1);

$task = new Fiber(function () {
    echo Fiber::getCurrent()->isRunning() ? "Сейчас готовим запрос доставки\n" : "Задача не выполняется\n";
    Fiber::suspend();
});
$task->start();
echo $task->isRunning() ? "Расчёт продолжает исполняться\n" : "Расчёт приостановлен, управление снаружи\n";
$task->resume();

Сейчас готовим запрос доставки
Расчёт приостановлен, управление снаружи

Внутри callback текущая задача running. После suspend выполнение вернулось вызывающему коду и задача suspended. Для вложенных Fiber флаг running родителя имеет отдельную тонкость: он не всегда означает, что именно родитель — текущий Fiber, это следующий опыт.

<?php
$parent = new Fiber(function () {
    $parent = Fiber::getCurrent();
    $child = new Fiber(function () use ($parent) {
        echo $parent->isRunning() ? "Родительский стек ещё активен\n" : "Родитель не активен\n";
        echo Fiber::getCurrent() === $parent ? "Текущий — родитель\n" : "Текущий — дочерний Fiber\n";
    });
    $child->start();
});
$parent->start();

Родительский стек ещё активен
Текущий — дочерний Fiber

Родитель вызвал start дочернего Fiber, а не собственный suspend. Поэтому наблюдаемый running и идентичность getCurrent отвечают на разные вопросы. Не используйте один флаг как универсальную проверку контекста.

<?php
declare(strict_types=1);

$task = new Fiber(function () { return 'Доставка: 300 руб.'; });
echo $task->isTerminated() ? "Смета готова\n" : "Смета ещё не рассчитана\n";
$task->start();
if ($task->isTerminated()) { echo $task->getReturn(), "\n"; }

Смета ещё не рассчитана
Доставка: 300 руб.

isTerminated проверяет окончание callback. В этом опыте окончание нормальное, поэтому getReturn доступен. При необработанном исключении Fiber также может быть terminated, но успешного результата не будет — это проверяется следующим примером.

<?php
$task = new Fiber(function () { throw new RuntimeException('Нет соединения'); });
$failed = false;
try { $task->start(); }
catch (RuntimeException $error) { $failed = true; echo $error->getMessage(), "\n"; }
echo $task->isTerminated() ? "Задача закончилась\n" : "Задача ещё жива\n";
echo $failed ? "Показать ошибку\n" : "Показать результат\n";

Нет соединения
Задача закончилась
Показать ошибку

Отдельный флаг failed хранит смысл завершения. isTerminated сообщает только состояние исполнения. Пользователю надо показать ошибку или результат согласно фактическому исходу, а не считать любой конец успехом.

<?php
echo Fiber::getCurrent() === null ? "Обычный внешний код\n" : "Есть текущая задача\n";
$task = new Fiber(function () { echo Fiber::getCurrent() instanceof Fiber ? "Внутри Fiber\n" : "Снаружи\n"; });
$task->start();
echo Fiber::getCurrent() === null ? "Обычный внешний код\n" : "Есть текущая задача\n";

Обычный внешний код
Внутри Fiber
Обычный внешний код

getCurrent возвращает выполняющийся Fiber либо null. До start и после возврата из него текущей задачи нет. Следующий awaitStock использует это, чтобы отказаться от suspend в неподходящем месте.

<?php
function awaitStock(string $sku): int {
    if (Fiber::getCurrent() === null) { throw new LogicException('Нужен контекст задачи'); }
    $stock = Fiber::suspend($sku);
    if (!is_int($stock)) { throw new UnexpectedValueException('Нужен целый остаток'); }
    return $stock;
}
try { awaitStock('A-10'); }
catch (LogicException $error) { echo $error->getMessage(), "\n"; }
$task = new Fiber(fn() => awaitStock('A-10'));
$task->start();
$task->resume(5);
echo $task->getReturn(), "\n";

Нужен контекст задачи
5

Своя ошибка объясняет требование API до вызова suspend. Если нужен синхронный режим, его следует реализовать отдельным ясным путём, а не возвращать фиктивный остаток 0.