Fibers and Async PHP

Reviewed & published by Brayan K

By the end of this lesson you'll understand PHP 8.1 Fibers — how to start, suspend, resume, and read a Fiber's getReturn value — what cooperative multitasking really means, how async runtimes like ReactPHP, Amp, and Swoole use Fibers to do non-blocking I/O without callbacks, and how generators (yield) compare.

Part of the free PHP course at LearnCodingFast — hands-on lessons with worked examples and the output they print, plus practice exercises and a quick quiz.

What You'll Learn in This Lesson

• Why PHP is synchronous and blocking by default
• Create a Fiber and drive it with start, suspend, and resume
• Read a Fiber's final value with getReturn
• What cooperative multitasking is (and is not)
• How ReactPHP, Amp, and Swoole use Fibers for async I/O
• How generators (yield) differ from Fibers

1️⃣ PHP Is Synchronous by Default

Out of the box, PHP runs one statement after another and blocks on I/O — a call like file_get_contents() stops the whole script until it returns. For a single web request that's simple and fast. But if one process must make many slow calls, it spends almost all its time waiting, doing nothing useful.

<?php
// PHP is SYNCHRONOUS and BLOCKING by default. Each line waits for the
// one before it. A slow call like this freezes everything after it.

function slowFetch(string $name): string
{
    // imagine this is a network call that takes a second
    return "data:" . $name;
}

echo slowFetch("a") . "\n";   // runs, then waits, then prints
echo slowFetch("b") . "\n";   // only starts AFTER "a" is fully done
echo "done\n";
?>

Notice slowFetch("b") can't even begin until slowFetch("a") has completely finished. Fibers give us a way to overlap that waiting.

2️⃣ Your First Fiber: start & suspend

A Fiber (PHP 8.1) is a block of code you can pause and resume, and it keeps its own call stack while paused. You wrap a callback in new Fiber(...), then start() it. Inside, Fiber::suspend($value) pauses and hands $value back to the caller; $fiber->resume($value) continues it, and that argument becomes the result of the suspend() call.

<?php
// A Fiber is a block of code you can PAUSE and RESUME.
// Introduced in PHP 8.1. It keeps its own call stack.

$fiber = new Fiber(function (): void {
    echo "1) fiber started\n";

    // Pause HERE and hand "halfway" back to the outside code.
    $resumeValue = Fiber::suspend("halfway");

    // Execution continues here when someone calls ->resume(...)
    echo "3) fiber resumed with: " . $resumeValue . "\n";
});

// start() runs the fiber until the first suspend(). It returns the
// value that suspend() handed out.
$suspended = $fiber->start();
echo "2) outside got: " . $suspended . "\n";

// resume() continues the fiber; the argument becomes the result of
// the suspend() call inside it.
$fiber->resume("go!");

echo "4) all done\n";
?>

Read the numbered lines in order: control ping-pongs between the Fiber and the outside code. The Fiber runs to its suspend(), hands a value out, and waits — exactly one of them is ever running at a time.

3️⃣ Suspending Repeatedly & getReturn

A Fiber can suspend many times, then finish by returning a value. You drive it in a loop with resume() until isTerminated() is true, and read the final value with $fiber->getReturn().

<?php
// A Fiber can suspend several times and then RETURN a final value.
// You read that value afterwards with getReturn().

$counter = new Fiber(function (): string {
    $total = 0;
    foreach (["x", "y", "z"] as $step) {
        $total++;
        // pause and report which step we're on
        Fiber::suspend("processing " . $step);
    }
    return "finished " . $total . " steps";   // becomes getReturn()
});

$status = $counter->start();            // runs to first suspend
while (!$counter->isTerminated()) {     // keep resuming until it ends
    echo $status . "\n";
    $status = $counter->resume();       // resume; capture next suspend value
}

echo $counter->getReturn() . "\n";     // the function's return value
?>

This pause-report-resume loop is the heart of a scheduler: each pass lets the Fiber make a little progress, then yields control so other work can run before it's resumed.

4️⃣ How Async Runtimes Use Fibers

Cooperative multitasking means each task runs until it voluntarily yields by suspending — nothing interrupts it, so there are no data races. Async runtimes (ReactPHP, Amp, Swoole) build an event loop on top of this: when your code awaits a network call, the runtime suspends the Fiber, lets the loop run other Fibers, and resumes yours when the data arrives. The result is async code that reads like ordinary blocking code — no callback pyramids.

<?php
// HOW ASYNC RUNTIMES USE FIBERS (simplified sketch of ReactPHP/Amp/Swoole).
// An event loop runs many fibers, suspending each one while it "waits"
// for I/O and resuming it when the result is ready. No callbacks needed.

$tasks = [];
foreach (["users", "orders"] as $name) {
    $tasks[] = new Fiber(function () use ($name): void {
        echo "start request: " . $name . "\n";
        // In a real runtime, suspend() yields control while the network
        // call is in flight; the loop resumes us when data arrives.
        Fiber::suspend();
        echo "got response: " . $name . "\n";
    });
}

// The "event loop": start every task, then resume them as I/O completes.
foreach ($tasks as $t) { $t->start(); }     // all requests kicked off
foreach ($tasks as $t) { $t->resume(); }    // all responses delivered
echo "loop finished\n";
?>

Both requests start before either response arrives — that's the overlap. In a real runtime the resume() calls are triggered by I/O completions, not a simple loop, but the shape is identical. This is also what powers long-lived WebSocket servers.

5️⃣ Generators (yield) vs Fibers

You may have met yield before — generators also pause and resume. The key difference: a generator can only yield from its own top-level body and is shaped like an iterator. A Fiber can suspend() from deep inside any nested function it calls, several frames down — which is precisely what makes transparent async possible, since the suspend point usually lives inside a library's networking code, not in your function.

<?php
// GENERATORS (yield) also pause and resume — but only the generator
// function ITSELF can yield, and it is shaped like an iterator.
// A Fiber can suspend from deep inside any nested call; yield cannot.

function steps(): Generator
{
    yield "one";
    yield "two";
    yield "three";
}

foreach (steps() as $value) {   // each loop pass resumes the generator
    echo $value . "\n";
}
?>

Generators were PHP's older, more limited tool for this. Fibers, added in 8.1, removed the restriction — which is why modern async frameworks moved onto them.

Now you try the two core skills — the start/suspend handshake, and reading a return value.

Fill in each ___ using the 👉 hint, then run it and check it against the Output panel.

<?php
// 🎯 YOUR TURN — start a Fiber, catch its suspended value, then resume it.
// Fill in each blank marked ___ , then run it.

$fiber = new Fiber(function (): void {
    echo "inside: before pause\n";
    Fiber::___("paused");      // 👉 the method that pauses a fiber
    echo "inside: after pause\n";
});

$value = $fiber->___();        // 👉 the method that begins the fiber
echo "outside got: " . $value . "\n";
$fiber->resume();              // continue the fiber to the end

// ✅ Expected output:
//    inside: before pause
//    outside got: paused
//    inside: after pause
?>

One more. Let the Fiber finish, then read the value it returned.

<?php
// 🎯 YOUR TURN — read a Fiber's final return value.

$fiber = new Fiber(function (): int {
    Fiber::suspend();          // pause once
    return 42;                 // this is the final return value
});

$fiber->start();               // runs to the suspend
$fiber->resume();              // runs to the return (terminates)

// Read the value the fiber returned:
echo "result: " . $fiber->___() . "\n";   // 👉 the method that reads the return

// ✅ Expected output:
//    result: 42
?>

Common Errors (and the fix)

• "Cannot suspend outside of a fiber" — you called Fiber::suspend() from the main script, not from inside a Fiber's callback. suspend() only works within a running Fiber.
• "Cannot resume a fiber that is not suspended" — you resumed a Fiber that has already terminated or hasn't been started. Check isTerminated() before resuming, and call start() exactly once first.
• getReturn() throws — you called it before the Fiber finished. getReturn() is only valid after the callback has returned and the Fiber is terminated.
• "class Fiber not found" — you're on PHP 8.0 or earlier. Fibers require PHP 8.1+; check with php -v.
• Expecting parallel speed-up on CPU work — Fibers don't run in parallel; only one runs at a time. They overlap waiting (I/O), so a tight CPU loop won't get faster.

Pro Tips

• 💡 You'll rarely write raw Fibers. Reach for Amp or ReactPHP, which run the event loop for you and use Fibers under the hood.
• 💡 Async shines for I/O, not CPU. Use it to fan out many HTTP/DB calls or hold thousands of WebSocket connections; for heavy computation use separate processes.
• 💡 Keep suspend points obvious. Whether raw or via a framework, know where your code can pause — that's where another task may run before you resume.

📋 Quick Reference — Fibers

Mini-Challenge: A Cooperative Scheduler

No code is filled in this time — just a brief and an outline. Build three Fibers, start them all, then resume them all, and watch the interleaving. This is the essence of how an event loop overlaps work without threads.

<?php
// 🎯 MINI-CHALLENGE: Build a tiny cooperative scheduler with Fibers.
// No code is filled in — work from the steps below, then run it.
//
// 1. Create THREE fibers. Each one echoes "task N: step 1", then calls
//    Fiber::suspend(), then echoes "task N: step 2".
// 2. Store them in an array.
// 3. Loop over the array and ->start() every fiber (you'll see all the
//    "step 1" lines first).
// 4. Loop again and ->resume() every fiber (now all the "step 2" lines).
// 5. This interleaving — start all, then resume all — is exactly how an
//    event loop overlaps work without threads.
//
// ✅ Expected output (order):
//    task 1: step 1 / task 2: step 1 / task 3: step 1
//    task 1: step 2 / task 2: step 2 / task 3: step 2

// your code here
?>

🎉 Lesson Complete!

• ✅ PHP is synchronous and blocking by default — it waits on each I/O call
• ✅ A Fiber (PHP 8.1) is code you can pause and resume, with its own stack
• ✅ Drive it with start → suspend → resume, and read getReturn() at the end
• ✅ Fibers give cooperative concurrency — one runs at a time, yielding voluntarily
• ✅ ReactPHP, Amp, and Swoole use Fibers to do async I/O without callbacks
• ✅ Generators (yield) pause only their own body; Fibers suspend from anywhere in the stack

Practice quiz

Continue this course

• Previous: Namespaces & PSR-4 Autoloading
• Next: Static Analysis with PHPStan & Psalm — Catch bugs before runtime with typed analysis, levels and CI integration
• Quick reference: PHP cheat sheet

Frequently asked questions

Do Fibers make PHP multi-threaded or parallel?

No. Fibers are a concurrency primitive, not parallelism. Exactly one Fiber runs at any instant on a single thread, and a Fiber keeps running until it chooses to suspend. What Fibers buy you is the ability to overlap waiting: while one Fiber is suspended waiting for a network response, another can run. That is ideal for I/O-bound work (HTTP calls, database queries) but does not speed up CPU-bound work, which still needs separate processes or an extension like parallel.

What is the difference between a generator (yield) and a Fiber?

Both can pause and resume, but a generator can only yield from its own top-level body and is shaped like an iterator — you drive it by iterating. A Fiber is more powerful: Fiber::suspend() can be called from deep inside any function the Fiber calls, several layers down the call stack, and control still returns cleanly to the code that resumed the Fiber. That deep, transparent suspension is exactly what async runtimes need, because the suspend point is often buried inside a library's networking code rather than in the code you wrote.

If I never call a runtime, what do start, suspend, resume, and getReturn actually do?

They are the four moving parts of the Fiber API. $fiber->start() begins the Fiber and runs it until the first Fiber::suspend() (or until it returns); start() returns whatever suspend() handed out. Fiber::suspend($value), called from inside the Fiber, pauses it and passes $value back out. $fiber->resume($value) continues the suspended Fiber, and the $value you pass becomes the result of the suspend() call inside. Finally, once the Fiber's callback has returned, $fiber->getReturn() gives you that final return value.

Do I write raw Fiber code in real applications?

Rarely directly. Fibers are a low-level building block. In day-to-day code you use an async framework — ReactPHP, Amp, or Swoole — that runs an event loop and uses Fibers internally. Their value is that they let those frameworks turn callback-heavy, deeply nested async code into ordinary-looking sequential code: you write what reads like a normal blocking call, and under the hood the framework suspends your Fiber while the I/O is in flight and resumes it when the data arrives.

Why is PHP synchronous by default, and when does async actually help?

Traditional PHP runs one request per process and executes top to bottom, blocking on each I/O call until it returns. For a typical web request that is simple and perfectly fast. Async helps when a single process must do many independent I/O operations that spend most of their time waiting — for example a service that fans out twenty HTTP calls, or a long-lived WebSocket server handling thousands of connections. There, suspending Fibers while requests are in flight lets one process keep busy instead of idling on each blocking call.