Fibers

Fibers are a low-level PHP feature for pausing and resuming execution. They make it possible for libraries to build cooperative concurrency, async runtimes, and code that looks synchronous while waiting for asynchronous work.

Most application developers should not write raw fiber scheduling code every day. You are more likely to use fibers indirectly through libraries and frameworks. Still, understanding the basic mechanics helps when debugging async PHP, event loops, queues, or framework internals.

A Basic Fiber

A fiber wraps a function that can suspend itself.

<?php

declare(strict_types=1);

$fiber = new Fiber(function (): string {
    echo 'Inside fiber before suspend' . PHP_EOL;

    $value = Fiber::suspend('paused');

    echo 'Inside fiber after resume with ' . $value . PHP_EOL;

    return 'finished';
});

$first = $fiber->start();

echo 'Fiber returned to caller with ' . $first . PHP_EOL;

$fiber->resume('resume value');

echo $fiber->getReturn() . PHP_EOL;

// Prints:
// Inside fiber before suspend
// Fiber returned to caller with paused
// Inside fiber after resume with resume value
// finished

start() begins the fiber. Fiber::suspend() pauses it and returns a value to the caller. resume() continues the fiber and sends a value back into the suspended point.

Fibers Are Cooperative

Fibers do not run in parallel by themselves. A fiber only pauses when it deliberately suspends. Something else must decide when to resume it.

That "something else" is usually an event loop or async runtime. The runtime can pause one task while it waits for I/O, then resume another task.

Raw fibers are therefore a building block, not a full async framework.

A Tiny Scheduler Example

This small example shows two fibers taking turns. It is not production-quality scheduling, but it shows the idea.

<?php

declare(strict_types=1);

function makeTask(string $name): Fiber
{
    return new Fiber(function () use ($name): void {
        echo $name . ' step 1' . PHP_EOL;
        Fiber::suspend();
        echo $name . ' step 2' . PHP_EOL;
    });
}

$tasks = [
    makeTask('A'),
    makeTask('B'),
];

foreach ($tasks as $task) {
    $task->start();
}

foreach ($tasks as $task) {
    if ($task->isSuspended()) {
        $task->resume();
    }
}

// Prints:
// A step 1
// B step 1
// A step 2
// B step 2

The tasks do not run at the same time. They cooperate by suspending and being resumed.

Why Libraries Use Fibers

Fibers help libraries hide callback-heavy async code behind normal-looking PHP.

For example, an async HTTP client may let code appear to wait for a response while the runtime actually suspends the current fiber and works on other tasks. When the response is ready, the runtime resumes the fiber.

That is why fibers matter even if you never instantiate new Fiber() yourself. They can change how modern PHP libraries implement concurrency.

Errors In Fibers

Exceptions thrown inside a fiber travel to the code that starts or resumes the fiber.

<?php

declare(strict_types=1);

$fiber = new Fiber(function (): void {
    throw new RuntimeException('Fiber failed.');
});

try {
    $fiber->start();
} catch (RuntimeException $exception) {
    echo $exception->getMessage() . PHP_EOL;
}

// Prints:
// Fiber failed.

Boundary code still needs proper error handling. Async code does not remove failures; it changes where they surface.

When Not To Use Raw Fibers

Do not use raw fibers just to make code look advanced. For most web applications, normal synchronous PHP is simpler and easier to debug.

If you need async I/O, use a proven library or framework that manages the event loop, scheduling, cancellation, timeouts, and error handling. Raw fibers are easy to misuse because scheduling is the hard part.

What You Should Be Able To Do

After this lesson, you should be able to explain that fibers pause and resume execution, recognise start(), suspend(), resume(), and getReturn(), and understand why fibers are usually used by libraries rather than directly in everyday application code.

For junior work, the practical skill is understanding the vocabulary when you meet async PHP tools, not hand-writing a scheduler from scratch.