Fibers (PHP 8.1)
debt(d8/e5/b3/t7)
Closest to 'silent in production until users hit it' (d9), scored d8. The detection_hints field states 'automated: no' and gives only a prose code pattern to watch for. No static analysis tool is listed. Misuse (e.g., blocking I/O inside a fiber, confusing fibers with threads, or missing null-checks on Fiber::getCurrent()) produces no compiler error, no linter warning, and no runtime exception in most cases — the code runs but behaves incorrectly or with degraded performance. Slightly better than d9 because blocking I/O misuse may surface in profiling or load testing before production.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix says to use an async framework (ReactPHP, Amp) rather than raw Fiber primitives. Migrating from naive direct Fiber usage to a framework-managed scheduler, or untangling blocking I/O calls spread across a CLI worker, requires changes across multiple files and a shift in the concurrency model — more than a single-line fix but typically contained within one service/component.
Closest to 'localised tax' (b3). The applies_to scope is narrowly 'cli, queue-worker' contexts on PHP 8.1+. Fibers are a low-level primitive typically hidden behind framework abstractions; they don't reach into the whole codebase. Once adopted, the concurrency model imposes a persistent but localised tax on maintainers working on that specific component, without strongly shaping the rest of the system.
Closest to 'serious trap (contradicts how a similar concept works elsewhere)' (t7). The misconception field explicitly states developers believe 'PHP Fibers provide multi-threading' when they are actually single-threaded cooperative coroutines. This directly contradicts how threads behave in languages like Java or Python's threading module, and even contradicts how 'async' is often understood (parallelism). The common_mistakes reinforce this: blocking I/O inside a fiber defeats the purpose entirely, an error that flows naturally from the multi-threading misconception.
Also Known As
TL;DR
Explanation
PHP 8.1 Fibers are full-stack, interruptible functions. A Fiber can be started, suspended via Fiber::suspend(), and resumed by the caller — enabling cooperative multitasking without threads or process forking. They form the basis for async PHP frameworks (Revolt, Amp, ReactPHP) by allowing I/O-waiting tasks to yield control rather than blocking. Unlike generators, Fibers can be suspended from anywhere in the call stack, not just at the top level.
Diagram
sequenceDiagram
participant SCHED as Scheduler
participant F1 as "Fiber 1<br/>HTTP call"
participant F2 as "Fiber 2<br/>DB query"
SCHED->>F1: start()
F1->>F1: begin HTTP request
F1-->>SCHED: suspend() - waiting for I/O
SCHED->>F2: start()
F2->>F2: begin DB query
F2-->>SCHED: suspend() - waiting for I/O
SCHED->>F1: resume() - I/O complete
F1-->>SCHED: return result
SCHED->>F2: resume() - I/O complete
F2-->>SCHED: return result
Note over SCHED: Single thread, cooperative concurrency
Common Misconception
Why It Matters
Common Mistakes
- Confusing fibers with threads — fibers are cooperative (yield-based), not preemptive; there is no parallelism.
- Not handling the case where Fiber::getCurrent() returns null — calling it outside a fiber context.
- Creating fibers for every small operation — the overhead of fiber management outweighs benefits for trivial tasks.
- Blocking inside a fiber with a regular blocking I/O call — defeats the purpose; use non-blocking I/O.
Code Examples
// Blocking inside a fiber — no concurrency benefit:
$fiber = new Fiber(function(): void {
$data = file_get_contents('https://api.example.com/data'); // Blocks!
Fiber::suspend($data);
});
// Use a non-blocking HTTP client; blocking calls negate fiber advantages// PHP 8.1 Fiber — cooperative concurrency primitive
$fiber = new Fiber(function(): void {
$value = Fiber::suspend('first suspension');
echo "Fiber received: $value\n";
Fiber::suspend('second suspension');
});
$val = $fiber->start(); // runs until first suspend → 'first suspension'
echo $val . "\n";
$val = $fiber->resume('hello'); // resumes, Fiber prints 'Fiber received: hello'
echo $val . "\n"; // 'second suspension'
$fiber->resume(); // Fiber completes