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 $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
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.
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.
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
yieldfrom 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()orresume()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.