Download the PHP package kode/context without Composer
On this page you can find all versions of the php package kode/context. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Vendor kode
Package context
Short Description 轻量级、高性能的 PHP 协程/纤程上下文管理库，支持分布式多机器部署与 W3C Trace Context 标准
License Apache-2.0
Homepage https://github.com/kodephp/context
Package context
Short Description 轻量级、高性能的 PHP 协程/纤程上下文管理库，支持分布式多机器部署与 W3C Trace Context 标准
License Apache-2.0
Homepage https://github.com/kodephp/context
FAQ
After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.
Example:
Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories.
In this case some credentials are needed to access such packages.
Please use the auth.json textarea to insert credentials, if a package is coming from a private repository.
You can look here for more information.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?
Informations about the package context
kode/context - PHP 协程/纤程上下文管理包
为多线程、多进程、协程（Swoole/Swow/Fiber）环境提供安全的请求上下文传递机制，支持分布式多机器部署
📌 概述
在现代 PHP 高并发编程中，尤其是在使用 协程（Coroutine） 或 纤程（Fiber） 的场景下，传统的全局变量、静态属性或单例模式极易导致上下文污染和数据错乱。例如，在一个 HTTP 请求中存储用户信息、Trace ID、请求对象等，若直接使用 static 变量或全局容器，多个并发协程会共享同一份内存，造成严重安全隐患。
kode/context 是一个轻量级、高性能、跨运行时的上下文管理库，旨在解决：
- ✅ Fiber 中
static变量被共享导致的数据污染 - ✅ Swoole/Swow 协程间上下文隔离问题
- ✅ 多进程（pcntl_fork）上下文继承与隔离
- ✅ 多线程（ZTS + parallel）上下文隔离
- ✅ 支持透明传递请求上下文（如：
user,request,trace_id） - ✅ 提供与 Go
context.Context类似的语义模型 - ✅ 兼容原生 PHP、Fiber（PHP 8.4+）、Swoole、Swow 等多种运行时环境
- ✅ 最低要求 PHP 8.4+（基于 WeakMap、enum、类型化常量等现代特性）
- ✅ 使用 final 类、类型安全、反射等更安全的方式实现
- ✅ 支持分布式多机器部署的上下文传递
🎯 为什么需要 kode/context？
| 场景 | 问题 | 解决方案 |
|---|---|---|
| 原生 PHP + 多进程 | 进程隔离，无需担心共享状态 | ✅ 安全 |
| 原生 PHP + 多线程（ZTS） | 线程共享内存，static 被所有线程共享 |
❌ 存在风险 |
| Swoole 协程 | 协程共享线程内存，static 被复用 |
❌ 极易污染 |
| Swow 协程 | 同上，绿色线程模型 | ❌ 存在上下文混淆 |
| PHP 8.4+ Fiber | Fiber 共享调用栈中的 static 变量 |
❌ 数据交叉污染 |
| 分布式多机器 | 跨节点调用时上下文丢失 | ✅ 序列化传递 |
👉 结论：只要存在"并发执行单元共享主线程内存"的情况，就必须使用上下文隔离机制！
🔥 特别提醒：这是解决 Facade 模式、Service Locator、静态容器等"全局状态"污染的关键！
🧩 核心功能
✨ v3 架构升级（WeakMap 隔离）
v3 是一次架构性重构，目标是彻底解决并发执行单元间的上下文污染，并补齐企业级可观测性与安全能力。
1. 真正的 Fiber / 协程隔离（WeakMap）
旧版使用全局 static 初始化标志 + 引用绑定，在多个 Fiber 并发时会发生数据串号（一个 Fiber 读到另一个 Fiber 写入的值）。v3 改为以「执行单元对象」（Fiber / Swoole 协程 / Swow 协程 / 线程）为键，存入 WeakMap，每个单元持有完全独立的 ContextStore：
- Fiber A 写入
user=alice，Fiber B 永远读不到，反之亦然； - 执行单元结束、对象被 GC 后，
WeakMap自动回收存储，无内存泄漏； - 同步环境退化为全局根存储，行为与旧版一致。
2. W3C Trace Context 标准（OpenTelemetry 互通）
新增 TraceContext 与 Context 集成方法，原生支持 traceparent / tracestate / baggage，可与 OpenTelemetry 无缝对接：
3. 安全反序列化（ValueSerializer）
跨进程 / 跨节点传递上下文时，默认不还原未知对象为实例，仅保留数组形态，杜绝对象注入攻击；支持白名单与自定义编解码：
头值 CRLF 清洗（防头注入）：toHeaders() / toW3CHeaders() 出站与
fromHeaders() / fromTraceparent() / fromW3CHeaders() 入站均自动剔除
tracestate / baggage / X-Context-* 值中的 CR / LF / NUL 控制字符（保留 HTAB），
杜绝经由上下文值的 HTTP 头注入（响应拆分 / 请求走私）。程序化
Context::set(REQUEST_ID, $untrusted) 等路径同样被出站清洗兜底。
4. 类型安全访问器与便捷 API
5. 作用域 RAII（ContextScope）
enter() 返回一个作用域句柄，离开作用域（或显式 close()）时自动回滚，避免手动 restore 遗漏：
6. Runtime 枚举
Kode\Context\Runtime 以枚举形式描述当前运行时（Fiber / Swoole / Swow / Thread / Process / Sync），并暴露 isCoroutine() / sharesMemory() / label() 等语义查询。
⚙️ 实现原理（按运行时自动适配）
| 运行时环境 | 上下文存储机制 | 说明 |
|---|---|---|
| PHP Fiber (8.3+) | WeakMap<Fiber, ContextStore> |
以当前 Fiber 对象为键持有独立存储，Fiber 回收后自动释放 |
| Swoole | WeakMap<Coroutine, ContextStore> |
基于协程对象绑定独立存储 |
| Swow | WeakMap<Coroutine, ContextStore> |
基于协程对象绑定独立存储 |
| 多线程 (ZTS) | 线程 ID + 独立存储 | 支持 parallel 扩展（ZTS 构建） |
| 多进程 | 进程 ID + fork 继承 | 支持 pcntl_fork |
| 普通同步环境 | 全局根存储 | 单线程安全，兼容 CLI/HTTP |
✅ v3 起，所有并发运行时统一采用
WeakMap<执行单元对象, 上下文存储>实现真正的「每执行单元独占隔离」，从根本上修复了旧版 Fiber 共享存储导致的数据污染问题（旧版static全局标志 + 引用绑定会在多个 Fiber 间串数据）。✅ 所有实现均保证：每个并发执行单元拥有独立的上下文视图
🧪 快速开始
1. 安装
2. 基本用法
3. 使用 Context::run() 创建隔离作用域
4. 使用 Context::fork() 继承上下文
5. 结合中间件使用（如 Swoole HTTP Server）
🔀 多进程支持
kode/context 提供完整的多进程上下文管理支持，适用于使用 pcntl_fork() 的场景。
Fork 上下文继承
进程池并行执行
进程间通信
进程间通过 socket 传递序列化数据：
🧵 多线程支持
kode/context 支持多线程环境（需要 ZTS + parallel 扩展）。
检测线程环境
线程中运行任务
线程池并行执行
🌐 分布式支持
kode/context 提供完整的分布式上下文传递支持，适用于微服务、多机器部署场景。
分布式追踪
W3C Trace Context（推荐）
原生支持 W3C traceparent / tracestate / baggage 规范，可与 OpenTelemetry 等标准链路系统直接互通：
序列化与反序列化
HTTP Headers 传递
完整分布式调用示例
与 kode/fibers 集成
kode/context 可以与 kode/fibers 无缝集成，在分布式任务调度中自动传递上下文：
🔄 API 文档
基础操作
| 方法 | 说明 |
|---|---|
Context::set(string $key, mixed $value): void |
设置上下文值 |
Context::get(string $key, mixed $default = null): mixed |
获取上下文值 |
Context::has(string $key): bool |
判断键是否存在 |
Context::hasAll(array $keys): bool |
判断所有指定键是否均存在（空数组返回 true） |
Context::hasAny(array $keys): bool |
判断是否存在任意一个指定键（空数组返回 false） |
Context::delete(string $key): void |
删除指定键 |
Context::clear(): void |
整体重置当前执行单元上下文（含作用域栈，使陈旧句柄失效） |
批量操作
| 方法 | 说明 |
|---|---|
Context::copy(): array |
复制当前上下文为数组快照 |
Context::restore(array $snapshot): void |
从快照恢复上下文 |
Context::merge(array $data, bool $overwrite = true): void |
合并数据到上下文 |
Context::keys(): array |
获取所有键名 |
Context::count(): int |
获取键值对数量 |
Context::all(): array |
获取所有数据 |
作用域操作
| 方法 | 说明 |
|---|---|
Context::run(callable $callable): mixed |
在隔离作用域中执行 |
Context::fork(callable $callable): mixed |
在继承作用域中执行 |
Context::runWith(array $initial, callable $callable): mixed |
以指定初始数据运行隔离作用域 |
Context::with(array $values, callable $callable): mixed |
批量注入键值后运行隔离作用域 |
Context::enter(?array $initial = null): ContextScope |
进入作用域，返回 RAII 句柄（自动回滚） |
Context::bind(callable $callable, ?array $snapshot = null): Closure |
绑定当前上下文到闭包，跨执行单元透传 |
Context::depth(): int |
当前作用域嵌套深度 |
Context::transaction(callable $callback): mixed |
在当前上下文执行回调，无论成功/异常均自动回滚到进入前快照 |
类型安全
| 方法 | 说明 |
|---|---|
Context::getOfType(string $key, string $type): object |
获取并断言对象类型 |
Context::getString(string $key, ?string $default = null): ?string |
类型安全获取字符串 |
Context::getInt(string $key, ?int $default = null): ?int |
类型安全获取整数 |
Context::getFloat(string $key, ?float $default = null): ?float |
类型安全获取浮点 |
Context::getBool(string $key, ?bool $default = null): ?bool |
类型安全获取布尔 |
Context::getArray(string $key, ?array $default = null): ?array |
类型安全获取数组 |
Context::getOrFail(string $key): mixed |
获取，缺失即抛 ContextException |
便捷 API
| 方法 | 说明 |
|---|---|
Context::getOrSet(string $key, Closure $factory): mixed |
不存在则惰性生成并写入 |
Context::add(string $key, mixed $value): bool |
原子追加到集合（不存在则创建数组） |
Context::pull(string $key, mixed $default = null): mixed |
取值并删除 |
Context::increment(string $key, int\|float $step = 1): int\|float |
自增（支持浮点） |
Context::decrement(string $key, int\|float $step = 1): int\|float |
自减 |
Context::push(string $key, mixed ...$values): void |
批量压入数组 |
Context::only(array $keys): array |
仅保留指定键的快照 |
Context::except(array $keys): array |
排除指定键的快照 |
监听器
| 方法 | 说明 |
|---|---|
Context::listen(string $key, Closure $listener): string |
注册变更监听器，返回监听 ID（* 为通配） |
Context::unlisten(string $key, ?string $id = null): void |
移除监听器 |
Context::listenedKeys(): array |
当前已注册监听的键列表 |
运行时信息
| 方法 | 说明 |
|---|---|
Context::runtime(): Runtime |
获取运行时枚举对象 |
Context::getRuntime(): string |
获取运行时类型 |
Context::isCoroutine(): bool |
是否在协程环境 |
Context::isThread(): bool |
是否在线程环境 |
Context::isProcess(): bool |
是否在进程环境 |
Context::isMain(): bool |
是否主执行单元（非子 Fiber/协程/线程） |
Context::isPostFork(): bool |
是否处于 fork 之后 |
Context::getExecutionId(): int\|string\|null |
获取执行单元 ID |
Context::getCoroutineId(): int\|string\|null |
获取协程 ID |
Context::getProcessId(): int |
获取进程 ID |
Context::getThreadId(): ?int |
获取线程 ID |
多进程操作
| 方法 | 说明 |
|---|---|
Context::prepareFork(): void |
准备 fork 前的上下文快照 |
Context::afterFork(bool $inherit = true): void |
fork 后初始化子进程上下文 |
Context::runInProcess(callable $task, bool $inherit = true): int |
在子进程中运行任务，返回 PID |
Context::waitProcess(int $pid): int |
等待指定子进程结束 |
Context::parallelProcesses(array $tasks, int $max = 4, bool $inherit = true, bool $throwOnError = true): array |
进程池并行执行（$throwOnError=false 时不抛异常，错误写入返回数组） |
多线程操作
| 方法 | 说明 |
|---|---|
Context::runInThread(callable $task, bool $inherit = true): object |
在线程中运行任务，返回 parallel\Future |
Context::parallelThreads(array $tasks, int $max = 4, bool $inherit = true): array |
线程池并行执行 |
分布式操作
| 方法 | 说明 |
|---|---|
Context::toJson(array $onlyKeys = []): string |
序列化为 JSON |
Context::fromJson(string $json, bool $merge = false): array |
从 JSON 反序列化 |
Context::export(array $onlyKeys = []): array |
导出可序列化数据（自动排除 __kode_ 内部瞬态键） |
Context::import(array $data, bool $merge = false): array |
导入数据（拒收 __kode_ 内部瞬态键） |
Context::startTrace(?string $traceId = null, ?string $nodeId = null): string |
启动内部追踪 |
Context::startSpan(): string |
创建子 Span |
Context::getTraceInfo(): array |
获取追踪信息 |
Context::isSampled(): bool |
是否采样 |
Context::setSampled(bool $sampled = true): void |
设置采样标志 |
Context::toTraceparent(): ?string |
导出 W3C traceparent |
Context::fromTraceparent(string $traceparent, ?string $tracestate = null): bool |
从 traceparent 继承（创建子 span） |
Context::setBaggage(string $key, string $value): void |
设置 W3C baggage 键值 |
Context::getBaggage(?string $key = null): array\|string\|null |
读取 baggage |
Context::toW3CHeaders(): array |
导出 traceparent/tracestate/baggage 为 HTTP Header |
Context::fromW3CHeaders(array $headers): bool |
从 HTTP Header 还原 W3C 上下文 |
Context::toHeaders(string $prefix = 'X-Context-'): array |
导出为自定义 Headers |
Context::fromHeaders(array $headers, string $prefix = 'X-Context-'): void |
从自定义 Headers 导入（键名须匹配 ^[a-z][a-z0-9_]{0,63}$） |
Context::continueTrace(array $headers, string $prefix = 'X-Context-'): void |
从上游 Header 继续追踪链路 |
Context::getDistributedKeys(): array |
获取分布式键 |
Context::exportForDistributed(): array |
导出分布式上下文 |
安全序列化（ValueSerializer）
跨进程 / 跨节点传递时用于安全编解码，默认不还原未知对象为实例（防注入）。
| 方法 | 说明 |
|---|---|
ValueSerializer::allow(string ...$classes): void |
将类型加入可信还原白名单 |
ValueSerializer::register(string $class, Closure $encode, Closure $decode): void |
注册自定义编解码器 |
ValueSerializer::isAllowed(string $class): bool |
是否在白名单 |
ValueSerializer::encode(mixed $value): mixed |
安全编码 |
ValueSerializer::decode(mixed $value): mixed |
安全还原（恶意载荷降级为数组） |
测试辅助
| 方法 | 说明 |
|---|---|
Context::reset(): void |
重置上下文状态 |
常量
🧱 设计思想参考
- Go 的
context.Context
提供了WithValue,WithCancel,WithTimeout等组合能力，本包聚焦于最核心的value传递。 - Swoole Coroutine\Context
借鉴其基于协程 ID 的上下文映射机制，确保隔离性。 - Hyperf\Context
对标其静态代理接口设计，提供更简洁的 API。 - OpenTelemetry
分布式追踪设计参考了 OpenTelemetry 的 Trace/Span 模型。
✅ 适用场景
- 微服务架构中的链路追踪（Trace ID 透传）
- 用户身份认证上下文（User / Token）
- 日志上下文注入（Structured Logging）
- ORM 连接上下文（如 Tenant ID）
- AOP 拦截器中共享临时数据
- 替代 Facade 模式中的全局状态
- 多进程任务并行处理
- 多线程计算密集型任务
- 分布式任务调度与上下文传递
🚫 注意事项
- 不建议存放大量数据（影响性能）
- 不支持跨协程/纤程通信（仅传递快照）
- 不应在上下文中保存资源句柄（如文件描述符、数据库连接）
- Fiber 下注意闭包绑定问题（
$this上下文可能不同） - 分布式传递时，对象会被序列化（经
ValueSerializer安全处理），资源句柄和闭包无法传递 - 多进程功能需要 pcntl 扩展
- 多线程功能需要 ZTS + parallel 扩展（不再依赖 pthreads）
- 最低运行环境为 PHP 8.4+
📦 与其他组件集成建议
| 组件 | 集成方式 |
|---|---|
| Hyperf | 替代 Hyperf\Context\Context，作为底层依赖 |
| Laravel Octane | 在 onRequest 回调中初始化 Context |
| EasySwoole | 在主服务启动时注册 Context 初始化 |
| Monolog | 添加 ProcessContextProcessor 注入 trace_id |
| kode/fibers | 作为底层依赖，支持分布式任务调度 |
🧪 性能基准测试
kode/context 在多种环境下进行了性能测试，迭代次数 100,000 次。
macOS (Apple Silicon)
| 方法 | 执行时间 | 每秒操作数 |
|---|---|---|
Context::set() |
8.53ms | 11,723,570 |
Context::get() |
6.87ms | 14,556,030 |
Context::has() |
6.53ms | 15,322,044 |
Context::delete() |
12.44ms | 8,038,464 |
Context::clear() |
18.80ms | 5,320,011 |
Context::copy() |
6.64ms | 15,064,102 |
Context::run() |
36.10ms | 2,770,016 |
Context::fork() |
42.50ms | 2,352,941 |
Context::toJson() |
~25ms | ~4,000,000 |
Context::fromJson() |
~30ms | ~3,300,000 |
测试环境： macOS 14.4 (Darwin 24.3.0), Apple M3 Pro (11核), 18GB RAM, PHP 8.3.30, OPcache 启用
Linux (x86_64)
| 方法 | 执行时间 | 每秒操作数 |
|---|---|---|
Context::set() |
~7ms | ~14,000,000 |
Context::get() |
~5ms | ~20,000,000 |
Context::has() |
~5ms | ~20,000,000 |
Context::run() |
~30ms | ~3,300,000 |
Context::fork() |
~35ms | ~2,800,000 |
测试环境： Ubuntu 22.04 LTS, AMD EPYC/Ryzen, PHP 8.2+, OPcache 启用
Windows (x86_64)
| 方法 | 执行时间 | 每秒操作数 |
|---|---|---|
Context::set() |
~9ms | ~11,000,000 |
Context::get() |
~8ms | ~12,500,000 |
Context::has() |
~8ms | ~12,500,000 |
测试环境： Windows 11, AMD Ryzen 7 5800H, 32GB RAM, PHP 8.2+
这些结果表明 kode/context 在各种操作上都具有出色的性能表现，适合在高并发环境中使用。
💡 提示： 实际性能会因硬件配置、PHP 版本、OPcache/JIT 状态等因素而有所不同。建议在正式环境中使用 OPcache 和 JIT 以获得最佳性能。
运行基准测试
🗂 版本要点
v3.2.0
clear()升级为「整体重置」：连同未关闭的作用域栈一起回收，并引入存储代数（epoch）守卫—— 此前创建的enter()/run()句柄在 clear 后析构时不再把陈旧快照覆盖回当前数据， 可安全用作常驻服务的请求边界清理手段（配合 kode/http 3.5 的Request::clear()收口）。ValueSerializer::encode()环检测 + 深度上限：对象图成环（如 PSR-7 请求与其属性互引） 不再无限递归爆栈，重复对象编码为reference标记、超深结构编码为truncated标记，解码为 null。- 内部瞬态键出入站隔离：
export()/toJson()一律排除__kode_前缀键 （如 kode/http 绑定的当前请求对象，含 Authorization/Cookie），import()/fromJson()拒收同名注入；copy()/transaction()快照语义不变，运行时对象照常随事务恢复。 fromHeaders()键名白名单化：仅接受^[a-z][a-z0-9_]{0,63}$，畸形键与内部前缀键直接丢弃。- 解码不再为未知类名触发自动加载：
enum_exists()探测关闭 autoload，杜绝经 JSON 载荷 投喂类名引发的自动加载副作用。
🤝 贡献与反馈
欢迎提交 Issue 或 Pull Request！
GitHub: https://github.com/kodephp/context
📜 许可证
Apache License 2.0
🌟
kode/context—— 让每一次协程调用都清晰可控，告别上下文污染！
All versions of context with dependencies
PHP Build Version
Package Version
Requires
php Version
^8.4
The package kode/context contains the following files
Loading the files please wait ...