PHP Fiber 如何让同步接口适配事件循环

我第一次把回调式客户端塞进已有 PHP 业务层时，最不舒服的不是异步本身，而是原来清楚的 return、throw 和 try/catch 全被拆散了。PHP Fiber 适合解决的正是这层“调用方式”问题：业务代码仍像调用同步方法一样往下写，底层在等待回调时暂停当前 Fiber，事件循环收到完成通知后再恢复它。

但边界要先说清：Fiber 不会把阻塞 I/O 自动变成非阻塞 I/O。它只是 PHP 8.1 起提供的完整调用栈、可中断函数。真正的 socket 就绪监听、定时器和回调调度，仍要由事件循环或异步扩展完成。

官方文档：https://www.php.net/manual/en/language.fibers.php

前置条件：先确认底层真的能异步通知

Fiber 是协作式调度。只有代码主动调用 Fiber::suspend()，控制权才会回到外部调度器。根据 PHP 官方说明，Fiber 可以在调用栈任意深度暂停，而且调用它的上层函数不必像 Generator 那样把返回类型改成 Generator。这让我们可以在基础设施层放一个暂停点，对业务层保留普通方法签名。

不过，如果底层调用本身是 file_get_contents()、传统阻塞数据库驱动或会长时间占用 CPU 的循环，外面套一层 Fiber 仍会卡住整个 PHP 进程。可适配的底层应该能把工作交给事件源，并以回调、Promise、事件或扩展通知“已经完成”。

先搭一个最小事件循环

为了看清控制权，我通常先写一个只支持“下一轮执行”和“延迟执行”的教学循环。它不是生产级网络轮询器，但足以表现两个关键边界：异步操作只负责登记完成回调；事件循环只在回调进入队列后执行它。

 */
    private array $timers = [];

    public function __construct()
    {
        $this->ready = new SplQueue();
    }

    public function defer(callable $callback): void
    {
        // 统一放到下一轮执行，避免在当前 Fiber 尚未暂停时立即恢复它。
        $this->ready->enqueue(Closure::fromCallable($callback));
    }

    public function delay(float $seconds, callable $callback): void
    {
        // 教学循环只保存到期时间；生产实现应交给真正的定时器驱动。
        $this->timers[] = [
            'at' => microtime(true) + $seconds,
            'callback' => Closure::fromCallable($callback),
        ];
    }

    public function run(): void
    {
        while (!$this->ready->isEmpty() || $this->timers !== []) {
            $now = microtime(true);

            foreach ($this->timers as $index => $timer) {
                if ($timer['at'] ready->enqueue($timer['callback']);
                    unset($this->timers[$index]);
                }
            }
            $this->timers = array_values($this->timers);

            if (!$this->ready->isEmpty()) {
                // 一次只取一个就绪回调，随后重新检查定时器。
                ($this->ready->dequeue())();
                continue;
            }

            // 没有就绪任务时短暂等待；真实事件循环会阻塞在 I/O 多路复用器上。
            usleep(1_000);
        }
    }
}

这里故意让 defer() 成为恢复 Fiber 的唯一入口。这样即使某个回调式 API 在注册时同步给出结果，也只会把恢复动作放进队列，而不会对仍处于 running 状态的 Fiber 调用 resume()。

用 awaitCallback 把回调包成同步返回值

适配器先拿到当前 Fiber，再把底层回调转换为事件循环中的恢复任务，最后调用 Fiber::suspend()。官方文档规定，传给 Fiber::resume() 的值会成为当前 Fiber::suspend() 的返回值，所以外层方法可以直接 return 它。

defer(function () use ($fiber, $value, $error): void {
            if (!$fiber->isSuspended()) {
                // 已取消或已结束的任务不再恢复，生产实现还应清理底层订阅。
                return;
            }

            if ($error !== null) {
                $fiber->throw($error);
                return;
            }

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

    // resume() 传入的成功值会从这里返回，throw() 则会从这里抛出异常。
    return Fiber::suspend();
}

我更愿意把 awaitCallback() 放在基础设施层，而不是散落到控制器和领域服务里。业务代码只看见一个返回普通值的方法，底层适配器才知道回调协议、事件循环和 Fiber 生命周期。

把同步外观接到定时器回调

下面用定时器模拟一个异步客户端。DemoClient::fetch() 不直接返回数据，只登记完成回调；SyncFacade::fetch() 则对上层暴露普通字符串返回值。这正是 Fiber 最有价值的地方：同步外观不等于同步阻塞，关键在于等待期间是否把控制权交回事件循环。

loop->delay(0.02, static function () use ($key, $done): void {
            if ($key === 'missing') {
                $done(null, new RuntimeException('记录不存在'));
                return;
            }

            $done('value:' . $key, null);
        });
    }
}

final class SyncFacade
{
    public function __construct(
        private MiniLoop $loop,
        private DemoClient $client,
    ) {}

    public function fetch(string $key): string
    {
        // 业务方法保持普通返回类型，异步细节封装在适配器内部。
        return awaitCallback(
            $this->loop,
            fn (callable $done) => $this->client->fetch($key, $done),
        );
    }
}

$loop = new MiniLoop();
$service = new SyncFacade($loop, new DemoClient($loop));

$task = new Fiber(function () use ($service): void {
    try {
        // 两次调用都保持顺序代码与普通异常处理方式。
        echo $service->fetch('profile'), PHP_EOL;
        echo $service->fetch('missing'), PHP_EOL;
    } catch (RuntimeException $error) {
        echo 'error: ', $error->getMessage(), PHP_EOL;
    }
});

// start() 会运行到第一个 suspend()，随后由事件循环接管恢复动作。
$task->start();
$loop->run();

按这段逻辑，第一项会输出 value:profile，第二项不会产生伪造的成功值，而是进入现有 catch，输出 error: 记录不存在。检查点不是“用了 Fiber 就异步”，而是每次等待时 $task->isSuspended() 为真，回调完成后才由事件循环恢复。

成功值与异常保持原有语义

Fiber::resume($value) 和 Fiber::throw($exception) 是一对非常实用的通道。前者把值作为暂停点的返回值，后者让异常从暂停点抛出。对调用 SyncFacade::fetch() 的代码来说，成功仍是返回值，失败仍是异常，不必额外检查“错误字段”或在每一层重复回调分支。

状态检查也不能省。PHP 官方文档说明，只有处于 suspended 状态的 Fiber 才能被 resume() 或 throw()；对其他状态调用会产生 FiberError。因此生产适配器至少要防住重复回调、取消后迟到的回调，以及 Fiber 已终止后仍尝试投递结果。

扩展到生产事件循环时要补什么

这个最小实验能解释原理，却不该直接代替成熟事件循环。我在真正项目里会把下列能力视为进入生产环境前的硬要求：

• I/O 驱动：使用能够监听 socket、stream 或扩展事件的循环，而不是靠毫秒轮询和 usleep()。
• 取消与超时：超时后既要让 Fiber 收到异常，也要从底层客户端移除监听，不能只丢弃迟到结果。
• 一次完成：用明确的 settled 状态保证成功、失败、取消三者只有一个能赢。
• 任务引用：事件循环要持有未完成 Fiber 或任务对象，避免业务代码丢失引用后难以管理生命周期。
• 未处理异常：顶层任务需要统一收集异常，否则一次恢复可能直接把错误抛到事件循环。
• 背压：Fiber 让代码更像同步，不代表可以无限创建请求；并发数、队列长度和连接池仍要限流。

PHP 8.4 以前，官方文档还特别指出对象析构函数执行期间不允许切换 Fiber。维护旧版本项目时，不要把可能暂停的工作藏进析构函数；资源释放最好放在显式的 finally 或生命周期方法中。

清理与判断：什么时候值得这样做

如果项目已经有成熟的 Promise API，并且业务层可以接受 Promise，继续使用现有抽象通常更简单。Fiber 适配更适合两类场景：一是要把回调式基础设施接到大量同步风格业务代码；二是框架本身已经用事件循环和 Fiber 提供结构化任务管理。它的收益是保留调用栈、返回值和异常语义，代价是必须认真管理任务状态、取消、背压与底层非阻塞能力。

我的最终判断很直接：先确认底层能异步通知，再用 Fiber 改善调用体验。如果底层仍是阻塞函数，Fiber 只是换了一层写法；如果事件循环已经能在等待期间继续处理其他任务，suspend / resume / throw 才真正把同步接口和异步调度连接起来。

常见问题

Fiber 是线程吗？

不是。Fiber 是协作式、可暂停的执行栈，不会并行运行，也不会自动抢占长时间计算。

可以在 Fiber 里直接调用阻塞数据库驱动吗？

可以调用，但调用期间仍会阻塞当前 PHP 进程，事件循环无法调度其他任务。要获得并发收益，需要非阻塞驱动、异步扩展或把阻塞工作移到独立进程/线程池。

为什么回调里不直接调用 resume？

因为有些 API 可能同步触发回调，此时 Fiber 还在 running 状态。先把恢复动作交给 defer()，等当前调用栈到达 Fiber::suspend() 后再恢复，更容易避免状态竞态。

一个 Fiber 结束后还能再次启动吗？

不能。Fiber 终止后应读取返回值或释放任务记录，下一次独立任务需要创建新的 Fiber。