PHP Fibers Explained — Async Concurrency, Internals & Production Patterns

<?php

// Requires PHP 8.1+
// This demo reveals the internal lifecycle of a Fiber step by step.

$emailSenderFiber = new Fiber(function (): string {
    // --- FIBER STARTS: runs when $emailSenderFiber->start() is called ---
    echo "[Fiber] Starting: connecting to mail server..." . PHP_EOL;

    // Suspend the Fiber, sending a status value OUT to the caller.
    // Execution pauses HERE. The local state (including this closure) is frozen.
    $recipientEmail = Fiber::suspend('waiting_for_connection');

    // --- FIBER RESUMES: runs when $emailSenderFiber->resume($value) is called ---
    // $recipientEmail now holds whatever value was passed into ->resume()
    echo "[Fiber] Resumed! Sending email to: {$recipientEmail}" . PHP_EOL;

    Fiber::suspend('sending_email');

    echo "[Fiber] Email sent. Fiber finishing." . PHP_EOL;

    // The return value of the fiber callable becomes available via ->getReturn()
    return 'email_delivered';
});

// --- OUTSIDE THE FIBER ---
// Fiber hasn't started yet. isStarted() === false
echo "Fiber created. Started: " . ($emailSenderFiber->isStarted() ? 'yes' : 'no') . PHP_EOL;

// ->start() begins execution inside the Fiber until the first Fiber::suspend()
// The value passed to Fiber::suspend() is returned by ->start()
$statusAfterStart = $emailSenderFiber->start();
echo "Fiber suspended. Status received: {$statusAfterStart}" . PHP_EOL;
echo "Is suspended: " . ($emailSenderFiber->isSuspended() ? 'yes' : 'no') . PHP_EOL;

// ->resume($value) passes a value INTO the fiber (it becomes the return of Fiber::suspend())
// and runs until the next suspension or completion
$statusAfterFirstResume = $emailSenderFiber->resume('alice@example.com');
echo "Fiber suspended again. Status received: {$statusAfterFirstResume}" . PHP_EOL;

// Resume with no value — the Fiber will finish (no more Fiber::suspend() calls)
$emailSenderFiber->resume();

// Now we can retrieve the Fiber's return value
echo "Fiber finished. Return value: " . $emailSenderFiber->getReturn() . PHP_EOL;
echo "Is terminated: " . ($emailSenderFiber->isTerminated() ? 'yes' : 'no') . PHP_EOL;

<?php

// A minimal but realistic Fiber-based task scheduler.
// Demonstrates how event loops like ReactPHP and Amp work under the hood.

class TaskScheduler
{
    /** @var Fiber[] Fibers that have not started yet */
    private array $pendingFibers = [];

    /** @var Fiber[] Fibers that are suspended and waiting to be resumed */
    private array $suspendedFibers = [];

    public function addTask(Fiber $fiber): void
    {
        $this->pendingFibers[] = $fiber;
    }

    public function run(): void
    {
        // Keep running until there's nothing left to do
        while (!empty($this->pendingFibers) || !empty($this->suspendedFibers)) {

            // Start all fibers that haven't begun yet
            foreach ($this->pendingFibers as $index => $fiber) {
                $fiber->start();  // runs until first Fiber::suspend()

                if ($fiber->isSuspended()) {
                    // Fiber yielded control — move it to the suspended queue
                    $this->suspendedFibers[] = $fiber;
                }
                // If the fiber completed without suspending, it just falls off
                unset($this->pendingFibers[$index]);
            }
            $this->pendingFibers = [];

            // Resume each suspended fiber once per scheduler tick
            // In a real event loop this is where you'd check stream_select()
            $stillSuspended = [];
            foreach ($this->suspendedFibers as $fiber) {
                if ($fiber->isSuspended()) {
                    $fiber->resume(); // let it run until next suspension or completion
                }

                if ($fiber->isSuspended()) {
                    // Still not done — keep it in the queue
                    $stillSuspended[] = $fiber;
                }
            }
            $this->suspendedFibers = $stillSuspended;
        }
    }
}

// Simulates an async HTTP API call that takes varying amounts of "time"
function simulateApiRequest(string $apiName, int $simulatedDelayTicks): void
{
    echo "[{$apiName}] Request initiated — suspending while waiting for response..." . PHP_EOL;

    // Each suspend() simulates one "tick" of I/O wait.
    // In production this would be a non-blocking socket read + stream_select.
    for ($tick = 0; $tick < $simulatedDelayTicks; $tick++) {
        Fiber::suspend(); // Yield control back to the scheduler
    }

    echo "[{$apiName}] Response received after {$simulatedDelayTicks} ticks!" . PHP_EOL;
}

$scheduler = new TaskScheduler();

// Task A: slow API — 3 ticks to respond
$scheduler->addTask(new Fiber(function () {
    simulateApiRequest('WeatherAPI', 3);
    echo "[WeatherAPI] Processing weather data..." . PHP_EOL;
}));

// Task B: fast API — 1 tick to respond
$scheduler->addTask(new Fiber(function () {
    simulateApiRequest('CurrencyAPI', 1);
    echo "[CurrencyAPI] Processing exchange rates..." . PHP_EOL;
}));

// Task C: medium API — 2 ticks to respond
$scheduler->addTask(new Fiber(function () {
    simulateApiRequest('GeoLocationAPI', 2);
    echo "[GeoLocationAPI] Processing location data..." . PHP_EOL;
}));

echo "=== Scheduler starting — watch how tasks interleave ===" . PHP_EOL;
$scheduler->run();
echo "=== All tasks complete ===" . PHP_EOL;

<?php

// =================================================================
// PART 1: Generator — can only suspend from the TOP LEVEL of itself
// =================================================================

function generatorFetchData(): Generator
{
    echo "[Generator] Fetching user..." . PHP_EOL;
    yield 'fetching_user'; // CAN suspend here — top level of generator function

    echo "[Generator] Fetching orders..." . PHP_EOL;
    yield 'fetching_orders';

    echo "[Generator] Done." . PHP_EOL;
}

// This works fine:
$gen = generatorFetchData();
$gen->current(); // runs to first yield
$gen->send(null); // runs to second yield
$gen->send(null); // runs to completion

echo str_repeat('-', 50) . PHP_EOL;

// But try to yield from a HELPER FUNCTION called by a generator...
// You need `yield from` or you can't suspend mid-helper. Painful for deep stacks.

// =================================================================
// PART 2: Fiber — CAN suspend from anywhere in the call stack
// =================================================================

// This is a deeply nested helper function — NOT a generator, just a plain function
function connectToDatabase(string $dsn): string
{
    echo "[DB Helper] Initiating connection to {$dsn}..." . PHP_EOL;

    // We can suspend FROM INSIDE this helper function!
    // A Generator cannot do this — it has no concept of "up the stack"
    Fiber::suspend('awaiting_db_connection');

    echo "[DB Helper] Connection established." . PHP_EOL;
    return 'db_connection_handle';
}

function fetchUserFromDatabase(int $userId): array
{
    // connectToDatabase is a plain function, not a generator
    // The Fiber suspend inside it still works perfectly
    $connectionHandle = connectToDatabase('mysql://localhost/myapp');

    echo "[DB Layer] Running SELECT query for user #{$userId}..." . PHP_EOL;
    Fiber::suspend('awaiting_query_result'); // suspend while query runs

    // In reality you'd read from a non-blocking socket here
    return ['id' => $userId, 'name' => 'Alice', 'email' => 'alice@example.com'];
}

$databaseFiber = new Fiber(function (): void {
    // This calls a regular function that calls another regular function
    // that suspends the fiber — impossible to do cleanly with generators
    $user = fetchUserFromDatabase(42);
    echo "[Fiber] Got user: {$user['name']} ({$user['email']})" . PHP_EOL;
});

echo "[Main] Starting database fiber..." . PHP_EOL;
$status = $databaseFiber->start();
echo "[Main] Fiber yielded: {$status} — simulating connection wait..." . PHP_EOL;

$status = $databaseFiber->resume();
echo "[Main] Fiber yielded: {$status} — simulating query wait..." . PHP_EOL;

$databaseFiber->resume();
echo "[Main] Fiber completed." . PHP_EOL;

<?php

// Production-grade Fiber runner with proper exception isolation.
// One Fiber failing must NOT kill the others.

class IsolatedFiberRunner
{
    /** @var array<string, Fiber> */
    private array $fibers = [];

    /** @var array<string, \Throwable> Exceptions captured from failed Fibers */
    private array $failures = [];

    /** @var array<string, mixed> Return values from successful Fibers */
    private array $results = [];

    public function register(string $taskName, Fiber $fiber): void
    {
        $this->fibers[$taskName] = $fiber;
    }

    public function runAll(): void
    {
        // Start all fibers — catch per-fiber exceptions so others aren't affected
        foreach ($this->fibers as $taskName => $fiber) {
            try {
                $fiber->start();
            } catch (\Throwable $exception) {
                // This fiber failed on startup — quarantine it
                $this->failures[$taskName] = $exception;
                unset($this->fibers[$taskName]);
                echo "[Runner] '{$taskName}' failed on start: {$exception->getMessage()}" . PHP_EOL;
            }
        }

        // Drive suspended fibers to completion
        $activeFibers = array_filter(
            $this->fibers,
            fn(Fiber $f) => $f->isSuspended()
        );

        while (!empty($activeFibers)) {
            foreach ($activeFibers as $taskName => $fiber) {
                try {
                    $fiber->resume();

                    if ($fiber->isTerminated()) {
                        // Safely collect the return value
                        $this->results[$taskName] = $fiber->getReturn();
                        echo "[Runner] '{$taskName}' completed successfully." . PHP_EOL;
                    }
                } catch (\Throwable $exception) {
                    // Fiber threw mid-execution — isolate, don't rethrow
                    $this->failures[$taskName] = $exception;
                    echo "[Runner] '{$taskName}' failed mid-run: {$exception->getMessage()}" . PHP_EOL;
                }
            }

            // Keep only fibers that are still suspended
            $activeFibers = array_filter(
                $this->fibers,
                fn(Fiber $f) => $f->isSuspended()
            );
        }
    }

    public function getResults(): array { return $this->results; }
    public function getFailures(): array { return $this->failures; }
}

$runner = new IsolatedFiberRunner();

// Task 1: succeeds after one suspension
$runner->register('fetch_config', new Fiber(function (): string {
    echo "[fetch_config] Loading remote config..." . PHP_EOL;
    Fiber::suspend();
    echo "[fetch_config] Config loaded." . PHP_EOL;
    return '{"debug": false, "max_retries": 3}';
}));

// Task 2: throws an exception mid-flight — should NOT crash other fibers
$runner->register('fetch_feature_flags', new Fiber(function (): string {
    echo "[fetch_feature_flags] Calling feature flag service..." . PHP_EOL;
    Fiber::suspend(); // suspend first to simulate async I/O
    // Simulating a transient service failure
    throw new \RuntimeException('Feature flag service returned HTTP 503');
}));

// Task 3: also succeeds — proves isolation works
$runner->register('fetch_user_prefs', new Fiber(function (): array {
    echo "[fetch_user_prefs] Fetching user preferences..." . PHP_EOL;
    Fiber::suspend();
    echo "[fetch_user_prefs] Preferences loaded." . PHP_EOL;
    return ['theme' => 'dark', 'language' => 'en-GB'];
}));

$runner->runAll();

echo PHP_EOL . "=== Results ==" . PHP_EOL;
foreach ($runner->getResults() as $taskName => $result) {
    $formatted = is_array($result) ? json_encode($result) : $result;
    echo "  {$taskName}: {$formatted}" . PHP_EOL;
}

echo PHP_EOL . "=== Failures ===" . PHP_EOL;
foreach ($runner->getFailures() as $taskName => $exception) {
    echo "  {$taskName}: " . $exception->getMessage() . PHP_EOL;
}