Kode/Runtime：统一PHP所有运行时的协程与并发编程，让代码丝般顺滑

引言

近年来，PHP 在常驻内存应用领域突飞猛进，Swoole、Swow 等扩展为 PHP 带来了真正的协程和高性能网络编程能力。PHP 8.1 更是在语言层面引入了 Fiber（纤程），为轻量级并发提供了原生支持。然而，这些技术的繁荣也带来了一个令人头疼的问题：API 碎片化。

开发者如果想构建一个能够兼容 Swoole、Swow、Fiber 甚至多进程/多线程环境的库或框架，往往需要编写大量的适配代码，处理底层差异，这无疑增加了心智负担和维护成本。

今天，我们要介绍一个优雅的解决方案——Kode/Runtime。它是一个专为现代 PHP 常驻内存应用设计的统一运行时抽象包，让你可以在任何运行时下使用同一套 API 编写并发代码，真正做到“一次编写，到处运行”。

背景：PHP 并发的“战国时代”

我们先来回顾一下 PHP 并发编程的现状：

• Swoole：功能强大的协程引擎，提供了完善的协程 API，但与其他环境不兼容。
• Swow：同样是协程扩展，但 API 设计与 Swoole 有所不同。
• PHP Fiber：语言内置的纤程，需要配合事件循环（如 Revolt）使用，API 较为底层。
• 多进程：通过 pcntl 实现进程隔离，但无法使用协程。
• 多线程：借助 pthreads 扩展（需要 ZTS 模式），API 又是一种风格。
• 传统 CLI：只能同步阻塞执行。

当你需要开发一个通用的库（比如一个 HTTP 客户端、一个任务队列）时，你不得不为每种环境编写不同的驱动，这不仅繁琐，还容易出错。Kode/Runtime 正是为了解决这一痛点而生。

什么是 Kode/Runtime？

kode/runtime 是一个 PHP 8.1+ 的包，它为各种运行时环境提供了一个统一的抽象层。你可以通过它调用协程、通道、延时执行等并发原语，而无需关心底层究竟是 Swoole、Swow、Fiber 还是普通的多进程/多线程。

核心设计理念：适配器模式 + 静态门面。用户通过 Runtime 类与抽象接口交互，底层适配器根据当前运行环境自动切换或手动指定。

• GitHub：kode-php/runtime
• Packagist：kode/runtime
• 许可证：Apache-2.0

核心特性一览

🔍 运行环境检测

自动识别当前是 Swoole、Swow、Fiber、多进程、多线程还是普通 CLI 模式。

echo Runtime::getName(); // 输出：SWOOLE | SWOW | FIBER | PROCESS | THREAD | CLI

🔄 统一协程启动

无论底层是哪种协程引擎，都通过 Runtime::async() 启动协程。

Runtime::async(function () {
    // 你的协程逻辑
});

⏱️ 跨平台睡眠

Runtime::sleep() 支持微秒级休眠，且在不同运行时下自动选择最合适的休眠方式（协程安全）。

Runtime::sleep(1.5); // 休眠 1.5 秒

📦 通道（Channel）抽象

提供了一个统一的通道接口，用于协程间的安全通信。

$channel = Runtime::createChannel(1); // 容量为1的通道
$channel->push($data);
$data = $channel->pop();

🧩 defer 清理机制

注册一个回调，在函数退出（包括异常）时自动执行，非常适合资源清理。

Runtime::defer(function () use ($fp) {
    fclose($fp);
});

🧠 上下文管理

通过 Context 类实现协程/线程安全的上下文存储，可以方便地传递请求级数据。

🛠️ 多进程与多线程支持

• 多进程：通过 Runtime::fork() 创建子进程（基于 pcntl）。
• 多线程：通过 Runtime::setEnvironment('thread') 切换到线程模式，然后使用 Runtime::async() 创建线程。

🧱 可扩展的适配器模式

框架内置了 Swoole、Swow、Fiber、Process、Thread、Cli 等多种适配器，你也可以轻松扩展新的运行时。

快速上手

1. 安装

composer require kode/runtime

2. 环境检测

use Kode\Runtime\Runtime;

echo "当前运行环境: " . Runtime::getName() . PHP_EOL;

3. 启动第一个协程

Runtime::async(function () {
    echo "协程开始" . PHP_EOL;
    Runtime::sleep(1.5); // 休眠1.5秒
    echo "协程结束" . PHP_EOL;
});

echo "主流程继续执行" . PHP_EOL;
Runtime::wait(); // 等待所有协程完成（在CLI/Fiber模式下需要）

4. 使用 Channel 通信

$channel = Runtime::createChannel(1);

Runtime::async(function () use ($channel) {
    $channel->push("Hello from coroutine");
    echo "生产者: 数据已发送\n";
});

Runtime::async(function () use ($channel) {
    $data = $channel->pop();
    echo "消费者: 接收到: $data\n";
});

Runtime::wait();

5. 使用 defer 清理资源

Runtime::async(function () {
    $fp = fopen('/tmp/test.txt', 'w');
    
    Runtime::defer(function () use ($fp) {
        fclose($fp);
        echo "文件已关闭\n";
    });

    fwrite($fp, "Hello");
    // 即使这里抛出异常，defer 也会执行
});

6. 多进程示例

Runtime::setEnvironment('process'); // 切换到多进程模式

$pid = Runtime::fork(function () {
    echo "子进程 PID: " . getmypid() . "\n";
    Runtime::sleep(1);
    echo "子进程完成\n";
});

echo "父进程 PID: " . getmypid() . "\n";
echo "创建的子进程 PID: $pid\n";
Runtime::wait();

7. 多线程示例（实验性）

Runtime::setEnvironment('thread'); // 需要 ZTS PHP 并安装 pthreads

$thread = Runtime::async(function () {
    echo "线程 ID: " . Thread::getCurrentThreadId() . "\n";
    Runtime::sleep(1);
    echo "线程完成\n";
});

Runtime::wait();

深入 API 解析

Runtime 类的静态方法提供了所有核心功能：

ChannelInterface：

interface ChannelInterface {
    public function push(mixed $data): void;
    public function pop(): mixed;
    public function close(): void;
    // ... 可能还有其他方法
}

Context（通过 kode/context 包集成）：

$context = Runtime::getContext();
$context->set('user_id', 123);
$userId = $context->get('user_id');

架构设计

Kode/Runtime 采用经典的适配器模式：

+------------------+
|    用户代码层    |
| Runtime::async() |
+------------------+
         ↓
+------------------+
| 抽象运行时接口   |
| (RuntimeInterface)|
+------------------+
         ↓
+--------+--------+--------+--------+
| Swoole| Swow | Fiber|Process|Thread|
|Runtime|Runtime|Runtime|Runtime|Runtime|
+--------+--------+--------+--------+

• RuntimeInterface 定义了所有运行时必须实现的方法。
• RuntimeAdapterFactory 负责根据当前环境或用户设置创建对应的适配器实例。
• 每个适配器（如 SwooleRuntime）内部调用底层 API 实现接口方法。

这种设计使得添加新的运行时（比如未来的 PHP 原生协程改进）变得非常简单。

兼容性与注意事项

注意：

• PHP 原生 Fiber 不支持抢占式调度，建议配合事件循环（如 Revolt）使用。
• 多线程目前是实验性功能，API 可能变化。
• 在多进程环境下，Runtime::wait() 会等待所有子进程退出。

性能与安全

• 类型安全：充分利用 PHP 8.1 的协变/逆变、readonly 等特性，接口设计严谨。
• 反射优化：缓存反射结果，避免重复解析。
• 内存管理：自动清理协程栈，防止内存泄漏。
• 异常处理：统一捕获协程内异常，避免进程崩溃。

应用场景与生态

Kode/Runtime 非常适合构建以下类型的库或应用：

• 通用 HTTP 客户端（兼容多种环境）
• 任务队列系统
• 微服务框架
• 实时通信中间件
• 分布式追踪（已集成 kode/context，支持 OpenTelemetry）

此外，项目还提供了实验性的 Runtime::runInCoroutine() 方法，可以自动将同步代码协程化，进一步简化迁移。

总结

kode/runtime 的出现，标志着 PHP 并发编程走向大一统。它让开发者可以摆脱底层运行时的束缚，专注于业务逻辑。无论你偏好 Swoole 的高性能，还是 Swow 的优雅，或是 Fiber 的原生，都能在统一的 API 下享受丝滑的编码体验。

如果你正在构建一个需要常驻内存的 PHP 应用，或者开发一个希望兼容多种运行时的库，不妨试试 kode/runtime。它会让你的代码更加简洁、可维护，也更具前瞻性。

附：可运行 Demo（并发 URL 抓取）

下面是一个完整的 demo，演示如何使用 kode/runtime 并发抓取多个 URL，并通过通道收集结果。

<?php

require 'vendor/autoload.php';

use Kode\Runtime\Runtime;

// 创建通道，用于收集结果
$resultChannel = Runtime::createChannel(10);

// 要抓取的 URL 列表
$urls = [
    'https://example.com',
    'https://httpbin.org/get',
    'https://jsonplaceholder.typicode.com/todos/1',
];

foreach ($urls as $url) {
    Runtime::async(function () use ($url, $resultChannel) {
        // 模拟 HTTP 请求（实际可使用兼容的 HTTP 客户端）
        // 这里用 sleep 模拟网络延迟
        $delay = rand(1, 3);
        Runtime::sleep($delay);
        
        $result = [
            'url' => $url,
            'content_length' => rand(100, 1000),
            'delay' => $delay,
        ];
        
        $resultChannel->push($result);
        
        // 使用 defer 记录完成日志
        Runtime::defer(function () use ($url) {
            // 在实际应用中，这里可以写日志或清理资源
            // echo "已完成: $url\n";
        });
    });
}

// 等待所有协程完成，并收集结果
$results = [];
Runtime::async(function () use ($resultChannel, &$results) {
    for ($i = 0; $i < count($urls); $i++) {
        $results[] = $resultChannel->pop();
    }
});

Runtime::wait(); // 等待所有协程结束

// 输出结果
echo "所有抓取完成：\n";
print_r($results);

运行说明：

• 确保已通过 Composer 安装 kode/runtime。
• 在命令行执行此脚本，根据你的环境（如果安装了 Swoole/Swow，会自动使用协程；否则降级为 Fiber 或同步执行）。
• 你会看到三个 URL 的抓取结果，它们会以随机的顺序输出，但总耗时由最慢的请求决定（并发效果）。

这个 demo 展示了 async、sleep、channel、defer 和 wait 的配合使用，完全屏蔽了底层运行时的差异。