Download the PHP package kode/fibers without Composer

🚀 Kode/fibers – 高性能 Fiber 协程池与协程调度器

面向 PHP 8.4+ 的高性能 Fiber 纤程客户端，兼容主流框架并提供可降级、可诊断、可扩展的并发执行能力。

✅ 特性概览

• ✅ PHP 8.4+ 原生 Fiber 支持（充分利用 typed constants、#[\Override]、json_validate() 等新特性，析构函数中可安全 suspend）
• 🧩 一键启用协程模式（非侵入式）
• 🔁 高性能 Fiber 池 + 自动回收机制
• 💬 Fiber 间通信：Channel、Queue
• 🛰️ 集成常见操作支持：MySQL、PgSQL、Redis、HTTP Client、文件 IO
• ⏱️ 超时控制、异常捕获、资源监控
• 🔄 任务重试机制
• 🖥️ CPU 核心感知 + 动态协程池配置
• 🔌 多框架适配：Laravel / Symfony / Yii3 / ThinkPHP8 / Plain PHP
• 🛠️ 命令行工具生成配置 & 注册服务
• 📝 原生 PHP 8.3 Attributes + PHPDoc 实现 IDE 完整识别
• 🚫 禁用函数检测 + 运行环境诊断

📊 性能基准（v4.9.0）

kode/fibers 在 v4.6.0 中加固了安全性并清理了死代码：删除了加载即崩溃的 EnableFibers 中间件、零引用的 TaskMutex 与 WebmanServiceProvider、以及伪装实现的 ProtobufProtocol；修复了文件事务存储的路径穿越、WebSocket 握手缺失校验与跨站劫持面、RPC/WebSocket 内部错误信息外泄、数据库存储的跨驱动 DDL/UPSERT 与命令注入等隐患。调度内核未改动，性能与 v4.5.0 持平（协程切换 ~9.1M、Channel ~24M、定时器 ~2.2M，均为 PHP 用户态最快 / 全场第一）。本库是纯 PHP、零 C 扩展的协程调度器，基于 PHP 官方 Fiber 原语实现，是 Swoole / Swow 之外的官方另一条协程路线——若你的场景追求极限原生吞吐且可接受扩展依赖，可直接选用 Swoole / Swow；若你更看重零扩展、框架原生、可静态分析与跨平台一致，本库即为此而生。在 PHP 8.3 + OPcache JIT 下与同类库（含原生协程引擎 Swoole / Swow）做真实横向压测，Channel 与定时器双双登顶全场最快，反超原生 Swoole / Swow：

数值为连续 3 轮取中位数（PHP 8.3.33，OPcache JIT tracing 开启，hrtime 计时）。本机 run-to-run 波动约 ±20–30%，单次跑可能落在区间内很大范围；历史文档中更高的切换 / Channel 数值属低负载单跑的噪声带上沿。reactphp/revolt 的「回调」维度为纯事件循环（无协程语义），仅作参考上限，不与协程级实现直接等价对比。原生 Swoole / Swow 为 C 层栈式协程，在 Zend VM 钩子上与本进程互斥，以独立子进程方式测量。完整方法论、环境与逐场景曲线见 docs/benchmark.md。

📖 项目背景

kode/fibers 旨在为 Laravel、Symfony、Yii3、ThinkPHP8 及自建框架提供统一的纤程运行时能力，减少业务接入并发模型时的改造成本。\ 项目重点解决三类问题：生产场景下的并发治理（池化、超时、重试、通信）、跨框架可移植性（统一配置与 CLI 初始化）、以及运行时可诊断性（环境诊断与自检）。

🧭 定位：纯 PHP 官方协程方案

kode/fibers 完全基于 PHP 官方 Fiber 原语（PHP 8.1+ 内置，8.4+ 最低支持）实现，不依赖任何 C 扩展：

• ✅ 零扩展、可静态分析：纯 PHP 实现，IDE、PHPStan、Psalm 全链路可分析；部署不挑平台、不被扩展绑定。
• ✅ 框架原生、可组合：Laravel / Symfony / Yii3 / ThinkPHP8 等一键接入，也可在裸 PHP 中直接使用。
• 🔁 与 Swoole / Swow 互补：二者在 Zend VM 钩子上以 C 层切换栈，原始吞吐更高（协程切换约 14–20M ops/s）；本库则在 Fiber 用户态下做到同类最快（切换 ~9M、Channel ~24M、定时器 ~2.2M）。按部署约束与吞吐需求自由取舍——更多选择，而非单一绑定。

💡 需要极限原生吞吐？直接 composer require swoole / swow 并在其协程环境中使用 kode/fibers 的运行时桥接（RuntimeBridge）；更看重轻量与一致性？仅 composer require kode/fibers 即可。

🔒 安全性与健壮性

v4.6.0 起，库在「性能」之外把安全性与健壮性列为同等优先的一等公民。已落实的加固：

• 路径穿越防护：FileTransactionStorage 对事务 ID 做强校验（仅 [A-Za-z0-9._-]），并经 basename 兜底，记录文件始终落在指定目录内。
• SQL 注入防护：DatabaseTransactionStorage 的表名经正则白名单校验；建表 / UPSERT 按驱动（MySQL / SQLite / PostgreSQL）分支生成，不再依赖单一方言。
• 命令注入防护：Php85Features::pipeExecute() 改为以数组形式直接交给 proc_open（不经 shell），从根本上消除注入面。
• 信息泄露防护：RPC / WebSocket 服务端不再向客户端回传内部异常详情（统一返回 Internal error）。
• 握手与跨站防护：WebSocketServer 校验 Upgrade / Connection / Sec-WebSocket-Version，并支持 setAllowedOrigins() 配置 Origin 白名单（防御 CSWSH）；读取请求头增加了行数 / 长度上限，避免内存耗尽。
• 死代码清理：移除加载即崩溃的 EnableFibers 中间件（缺失 psr/http-server-middleware 依赖）、零引用的 TaskMutex 与 WebmanServiceProvider、以及伪装实现的 ProtobufProtocol；IntegrationManager 修正了服务提供者命名空间映射并移除 eval。

凡涉及网络监听的组件（RpcServer / WebSocketServer / WebUI）默认绑定 0.0.0.0 且不带鉴权。生产环境请置于反向代理 / 防火墙之后，并对 WebSocket 配置 setAllowedOrigins()。

🏃 常驻进程下的并发原语（v4.11.0）

HTTP worker / queue consumer 这类「一个进程服务很多次请求」的形态下，协程原语的语义与一次性脚本不同。本版本修正了四处：

1. 取消信号在挂起窗口内不再丢失

Coroutine::cancel() 是把异常投进当前挂起点（Suspension）的。若信号正好落在「上一次挂起已被定时器唤醒、下一次 park() 尚未登记」的窄窗口里，目标的 Suspension 已 pending=false，throw() 直接空转——任务一路跑完还"正常返回"。实测（1ms 步进睡眠 / 4ms 超时）约 1/4 概率命中。现在 Scheduler::park() 在登记挂起点后立即补投一次未决取消：挂起点本就是取消承诺的投递时刻，这是唯一不漏的位置。

2. 循环外创建的超时令牌按单调时钟惰性判定

CancellationTokenSource::withTimeout()（对外即 Fibers::timeoutToken()）过去无条件走 Scheduler::current() ?? Scheduler::default()。在事件循环外调用时拿到的是进程级默认调度器单例，而没人驱动它的 run()：定时器永不触发，超时形同不存在，闭包还会把令牌源永久钉在单例上（常驻进程里的无界泄漏）。现在循环外改为登记截止点（Scheduler::now() 单调时钟），由下一次 isCancelled() / reason() / throwIfCancelled() / subscribe() 观察动作落实取消；循环内仍走定时器，中断精确到点。

显式传入 $scheduler 时依旧走定时器——那等于调用方承诺"我自己驱动这个循环"。

3. Mutex 按协程认持锁者

纤程（Fiber）是池化复用的：A 协程跑完后它的 Fiber 会被借给 B 协程。以 Fiber 认人，B 会误判为"A 正在重入加锁"而放行，还能解开一把自己从没拿过的锁（互斥语义直接失效）。现在持锁身份取 Scheduler::currentCoroutine()，一个任务一个句柄；同一协程重复 lock() 仍报「不支持重入」，非持锁协程 unlock() 仍报「只有持锁协程可以解锁」。

4. 没人读取的协程异常会被上报

go() / async() 出去的任务抛了错、结果却从没被 join()：以前只登记进内部列表（unhandledErrors() 全仓无人调用），异常在进程里蒸发——表现为静默的数据不一致，日志里一个字都没有。现在事件循环收尾时会把「上一轮就已失败、过了整整一个循环仍无人读取」的异常交给 setErrorHandler()，未设置则直写 stderr。

一轮宽限是必要的：Runtime::execute() 的形状是 go() → run() → join()，join() 就在 run() 返回之后，立即定性会误报。

调度器销毁时（含脚本正常退出）会自动 flush 一次，所以下面这种一次性写法也不会漏：

已知边界：Fibers::async() 在循环外落到进程级默认调度器单例，而它同样没人驱动——那些任务不会自己跑完，却活到下一次有人 run() 那个单例，在常驻 worker 里表现为跨请求重放旧任务。本版本没有改这个语义（改了会让现有依赖 async() 惰性驱动的写法全部失效）。需要隔离时用 Scheduler::resetDefault() 丢弃单例，或 Scheduler::default()->clear() 清空待执行队列；生产代码请优先在循环内用 go()，或干脆 new Scheduler() 自带生命周期。

🏷️ 版本自述（v4.12.0）

Fibers::VERSION 常量与 Fibers::version() 暴露本包版本，用于诊断输出与运行时核对：

composer.json 的 version 字段是 composer 侧的权威值，类常量是它的交叉核对副本—— tests/VersionGuardTest.php 在两者不一致时直接失败，杜绝「tag 打了、常量忘改」的漂移。

⚙️ PHP 8.5 兼容与便捷 API

新增便捷入口以降低接入成本并兼容未来 PHP 8.5 运行时能力：

新增健壮架构 API

• 上下文并发透传：Fibers::concurrentWithContext()
• 健壮单任务：Fibers::resilientRun()
• 远程调度分发：Fibers::scheduleDistributedRemote()
• 运行时桥接：Fibers::runtimeBridgeInfo()、Fibers::runOnBridge()
• 可视化监控：Fibers::profile()、Fibers::profilerDashboard()
• ORM 适配层：Fibers::eloquent()、Fibers::fixtures()

对应文档：

• 上下文传递机制
• 运行时桥接
• Profiler 可视化面板
• ORM 适配层

📦 安装

框架快速集成（可选）

使用内置命令工具初始化框架配置：

各框架特定命令：

环境要求检查

安装完成后，可以运行诊断命令检查环境兼容性：

诊断结果将显示PHP版本、禁用函数、必要扩展等信息，并给出优化建议。

🧱 架构设计原则

本包采用 “轻量内核 + 插件扩展” 设计：

所有组件均实现 PSR 标准，支持 DI 容器注入。

🧪 快速开始

1. 基础使用：一键启动纤程任务

使用门面或辅助函数快速启动纤程：

2. 使用纤程池（推荐生产环境）

纤程池支持资源复用、超时控制和错误重试：

🧰 核心功能详解

✅ 1. PHP 版本兼容性处理

✅ PHP 8.4 起：允许在 __destruct() 中调用 Fiber::suspend()（v5.0.0 起最低要求 PHP 8.4+）

在 PHP 8.4 之前，析构函数中调用 Fiber::suspend() 会触发 Error；v5.0.0 起包要求 php: ^8.4，composer 安装阶段即保证运行时满足此语义，因此早期版本用于规避该限制的「安全析构模式 / 延迟析构任务队列」机制已整体移除（Fibers::enableSafeDestructMode() 保留为空操作、Fibers::deferDestructTask() 直接立即执行，以兼容旧调用方）。

✅ 2. 纤程池（Fiber Pool）高级用法

获取 CPU 数量（用于动态配置）

自定义池配置示例

支持的操作类型

💡 提示：建议配合异步 I/O 扩展如 swow 或 swoole 使用以获得最佳性能。

✅ 3. 多框架适配方案

Kode/fibers提供了统一的API和自动检测机制，可以无缝集成到各种PHP框架中：

统一配置结构 (config/fibers.php)

框架集成示例

Laravel 集成:

Symfony 集成:

Yii3 框架集成:

ThinkPHP8 框架集成:

原生 PHP 项目:

✅ 4. 纯 PHP Fiber API + IDE 可识别设计

Kode/fibers 提供完整的 IDE 支持与类型安全，无需任何运行期魔法：

Kode/fibers 基于 PHP 原生 Fiber 原语，不依赖运行期注解（Attribute）内省，调用方式即文档：

✅ 在 PhpStorm / VSCode + Intelephense 中均可获得完整补全（基于 Fibers / Facades\Fiber 的 @method 声明）。

✅ 5. 通信机制：Channel

Kode/fibers 提供强大的纤程间通信机制，核心原语是 Channel（类似 Go Channel）：

创建通信通道（类似 Go Channel）

发布/订阅模型（Event Bus）

注：本库当前以 Channel 作为纤程间通信的核心原语；早期版本提供的 Kode\Fibers\Event\EventBus 发布/订阅组件已移除（未被内核引用）。如需事件总线，可基于 Channel 自行封装，或接入外部消息中间件。

✅ 6. 禁用函数检测与环境诊断

Kode/fibers提供了全面的环境检测功能，可以识别潜在的兼容性问题：

检测黑名单函数

常见禁用函数影响

✅ 我们会在初始化时尝试模拟这些函数的安全替代品。

📘 使用场景指南

🧩 何时使用 Fiber::run()？（一键协程）

适用于小规模并发请求，无需长期维护状态：

✅ 优点：零配置、无副作用\ ❌ 缺点：无法复用、无资源管控

🏗️ 何时使用 FiberPool？（生产推荐）

适用于高并发服务，如微服务网关、批量任务处理器：

✅ 支持：

• 资源复用
• 错误重试
• 超时熔断
• 监控埋点
• 并发控制

🛠️ CLI 命令列表

Kode/fibers提供了一系列命令行工具，方便开发和管理：

常用命令选项

🔄 自动降级机制

kode/fibers 支持智能降级，根据已安装的依赖包自动选择最佳实现：

安装方式

功能对比

使用示例

🧩 功能实现状态

✅ 已实现功能

• [x] 上下文传递机制：使用 kode/context 实现纤程上下文变量传递，支持跨设备
• [x] 分布式 Fiber 调度：DistributedScheduler 支持跨机器任务调度
• [x] 性能监控面板：FiberProfiler 和 WebUI 可视化监控（已合并）
• [x] 生态系统集成：RuntimeBridge 支持 Swoole/OpenSwoole/Swow/Workerman 桥接
• [x] ORM 适配层：EloquentAdapter 和 FixturesAdapter 支持 Eloquent、Doctrine 等
• [x] 断路器模式：CircuitBreaker 实现自动熔断和恢复机制
• [x] 负载均衡：RoundRobinBalancer 智能任务分发算法
• [x] 热重载支持：HotReloader 实现不中断服务更新代码
• [x] 可视化管理界面：WebUI 提供 Web UI 管理纤程池和任务
• [x] 连接池支持：ConnectionPool 支持 PDO、Redis 连接池管理
• [x] 协程调试器：FiberDebugger 支持断点、日志、状态监控
• [x] PHP 8.5 特性支持：Php85Features 自动适配新特性
• [x] 多框架支持：Laravel、Lumen、Symfony、Hyperf、Yii3、ThinkPHP8

详细开发计划见 路线图文档。

📚 参考资料

• PHP Fibers RFC - PHP 官方纤程规范
• PHP 8.1 Fibers 文档 - 官方 API 文档
• Swoole Coroutine Docs - Swoole 协程文档
• Swow Fiber Guide - Swow 框架纤程指南
• Go Channels in PHP - PHP 中的 Go 通道实现
• RevoltPHP Event Loop - 事件循环实现参考

🙌 贡献者

欢迎提交 PR！请确保：

• ✅ 单元测试覆盖率 ≥ 90%
• ✅ 符合 PSR-12 编码规范
• ✅ 更新文档与 CHANGELOG

📄 许可证

Apache License 2.0 - 参见 LICENSE 文件。

Maintained by Byte Team - Kode PHP Lab\ 🌐 https://github.com/Kode-php/fibers