Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Concepts and Reference

PHP Fibers

Reference for PHP Fibers (PHP 8.1): the Fiber class, start, suspend, resume, throw, getReturn, status methods, schedulers and common mistakes.

A fiber is a function with its own call stack that can pause itself in the middle of execution and be resumed later. Fibers arrived in PHP 8.1 through the Fiber class. They give you cooperative multitasking: only one fiber runs at a time, and control changes hands only at explicit Fiber::suspend() calls.

Fibers are the building block for async libraries such as Revolt, Amp and ReactPHP. Application code rarely uses them directly, but the mechanics are small enough to learn in a few minutes.

PHP
<?php
$fiber = new Fiber(function (string $name): string {
    $reply = Fiber::suspend("hello $name");
    return "got $reply";
});
$out = $fiber->start("Ada");   // "hello Ada"
$fiber->resume("hi");
echo $fiber->getReturn();      // got hi

Try it

PHP Start, suspend, resume, return

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP A round-robin scheduler

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP Throwing into a fiber

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The Fiber API

Member Description
new Fiber(callable $callback) Creates a fiber. Nothing runs yet.
start(mixed ...$args): mixed Runs the callback until it suspends or ends. Returns the suspended value, or null if it finished.
resume(mixed $value = null): mixed Continues after the pending Fiber::suspend(), which returns $value.
throw(Throwable $e): mixed Continues by throwing $e at the suspension point.
getReturn(): mixed The callback's return value. Only valid once the fiber has terminated.
isStarted(), isSuspended(), isRunning(), isTerminated() Status checks.
Fiber::suspend(mixed $value = null): mixed Static. Pauses the current fiber and hands $value to whoever called start() or resume().
Fiber::getCurrent(): ?Fiber The running fiber, or null in the main code.

Misuse throws FiberError: starting twice, resuming a fiber that is not suspended, calling Fiber::suspend() outside a fiber, or calling getReturn() too early.

Usage notes

  • A fiber can suspend from any depth of nested calls, not only from its top-level function. That is the difference from generators, which can only yield from their own body.
  • Fibers do not run in parallel and do not make blocking calls (sleep(), file_get_contents() on a socket) non-blocking. An event loop with non-blocking I/O is what provides concurrency.
  • An exception that escapes the fiber function is rethrown from the start() or resume() call that was running it.
  • Each fiber has its own stack, so thousands of them are fine, but each costs some memory.
  • Prefer a library (Revolt, Amp) over hand-written schedulers in production.