Download the PHP package kode/session without Composer

kode/session

高性能分布式会话管理器，支持文件、Redis、Cookie 等多种驱动，可独立使用或集成到其他框架中。

特性

• 多驱动支持：File、Redis、Cookie、Array（内存）、Database（PDO）等存储驱动
• 分布式会话：Redis / Database 驱动支持跨机器共享 session
• 数据库驱动：基于 PDO，兼容 SQLite / MySQL / PostgreSQL，一行一键模型 + 跨库 upsert + 抢占式分布式锁
• 透明加密：可开启 AES-256-GCM 透明加密，落库数据均为密文（密钥由 secret 经 PBKDF2 衍生），存储泄漏也无法还原明文
• 透明压缩：可开启 gzip 压缩，落库体积显著缩小（大会话尤为明显），与加密可叠加（先压缩后加密）
• 强类型访问器：getInt/getFloat/getBool/getString/getArray 按目标类型强制转换，避免手动类型判断
• 延迟写盘：set/delete 仅更新内存与脏标记，落盘推迟到 save()/close() 一次性批量完成，减少 I/O 往返
• 概率化 GC：中间件按 gc_probability/gc_divisor 概率触发回收，避免每请求扫描过期数据
• 协程安全：不使用全局 $_SESSION，支持 PHP Fiber/协程
• 请求隔离：支持配合 kode/context 做请求内会话隔离
• 进程/并行支持：支持多进程并发访问，带分布式锁
• PSR-7/15 兼容：完整的中间件支持
• 闪存数据：类似 Laravel/ThinkPHP 的 flash 功能（支持 now/old/keep）
• 安全加固：会话 ID 强校验（防路径穿越与会话固定）、Cookie 驱动 HMAC 签名防篡改、regenerate 数据迁移
• 异常体系：分层异常（SessionException 及子类）便于精准捕获
• PHP 8.3+：使用枚举、只读属性、#[\Override] 等现代特性

安装

快速开始

基本用法

使用中间件

驱动

File 驱动

本地文件存储，适合单机部署。

Redis 驱动

分布式存储，适合多机器部署。

Redis 驱动支持两种连接方式：

• phpredis 扩展（优先）
• predis 包（composer require predis/predis）

Cookie 驱动

基于客户端 Cookie 存储，适合轻量级场景。

注意：Cookie 有大小限制（通常 4KB），只适合存储少量数据。

Array 驱动

纯内存存储，适合测试、CLI 与临时会话（进程结束即释放）。

Database 驱动

基于 PDO 的数据库存储，兼容 SQLite / MySQL / PostgreSQL，适合已有数据库基础设施、希望会话入库的场景。

• 建表幂等：kode_sessions(id, name, payload, expire) 与 kode_session_locks(id, token, expire)。
• upsert 采用「先 UPDATE 后 INSERT + 23000 冲突回退」的跨库兼容写法，不依赖特定方言。
• 分布式锁基于独立锁表（INSERT 抢占 / 过期可重新认领），跨数据库通用。
• 通过 SessionManager 使用时只需在 drivers 配置 database 项并设 default => 'database'。

透明加密

任意驱动均可开启透明加密，写入存储层前对值做 AES-256-GCM 加密，存储泄漏也无法还原明文。

• 密钥由 secret 经 PBKDF2-SHA256 衍生为 AES-256 密钥，无需直接使用弱密钥。
• 每条密文携带独立随机 IV 与 GCM 认证标签，防重放与篡改。
• 解密失败（密钥不符 / 数据被篡改）时自动降级为默认值，不会抛异常。
• 密文以 kenc1: 前缀标识，未开启加密的旧数据可向后兼容读取。

透明压缩

任意驱动均可开启 gzip 压缩，对写入存储层的值做压缩，显著降低落库体积（文本类 / 大数组类会话尤为明显）。压缩与加密可同时开启，处理顺序为「先压缩后加密」，加密层还能进一步掩盖压缩特征。

• 依赖 ext-zlib（PHP 内置扩展，已在 composer 中声明）。
• 压缩载荷以 kz1: 前缀标识；极端情况下压缩失败时降级为未压缩存储（kz0: 前缀），保证数据可还原、不丢会话。
• 未开启压缩的旧数据向后兼容读取。

强类型访问器

读取时按目标类型强制转换，省去手动 is_numeric / filter_var 判断：

每个方法都带类型默认值（如 getInt('x', 7)），缺失或非可转换值时返回默认值。

延迟写盘（lazy write-through）

set/delete 只更新内存与脏标记（dirty / removed），真正落盘推迟到 save()/close() 一次性批量完成，减少每个 set 触发的驱动 I/O（文件重写 / Redis 往返）。

• isDirty() / hasChanges() 反映是否存在待落盘的变更。
• regenerate()、destroy()、close() 会先刷写未落盘的变更，避免丢失本请求写入。

概率化垃圾回收（GC）

中间件按概率触发 GC，避免每请求都扫描过期数据：

也可在 SessionManager 全局配置 设置 GC 默认值（中间件配置优先级更高）：

或运行时动态调整：

也可手动在长周期任务中调用 $manager->gc($maxLifetime, $config) 强制回收。

驱动列表

配置

SessionManager 配置

中间件配置

API 文档

Session 类

基本操作

数据存取

进阶操作

闪存数据

闪存数据只在当前请求和下一次请求中可用。

错误/成功信息

CSRF 保护

SessionManager 类

协程安全

本包不使用全局 $_SESSION，完全在内存中管理 session 数据，支持 PHP Fiber/协程。

Fiber 中的使用

请求隔离

配合 kode/context 做请求内会话隔离：

分布式和并行

分布式锁

Redis 驱动支持分布式锁：

多进程支持

框架集成

集成到自定义框架

目录结构

测试

性能提示

1. File 驱动：适合开发环境和小规模部署
2. Redis 驱动：生产环境推荐，支持分布式和高并发
3. Cookie 驱动：仅用于轻量级场景，不适合存储大量数据
4. Database 驱动：适合已有数据库基础设施、希望会话入库的场景；采用跨库 upsert 与抢占式锁
5. 延迟写盘：批量 set/delete 只在 save() 时落盘一次，避免每个 set 触发驱动 I/O
6. 透明加密：开启后写入为密文，加解密有少量开销，仅对敏感场景建议开启
7. 透明压缩：对文本 / 大数组类会话可显著缩小落库体积、降低 I/O，与加密叠加时「先压缩后加密」几乎不增加额外开销
8. GC 回收：中间件按概率触发，必要时可在长周期任务中手动调用 $manager->gc() 清理过期 session

驱动扩展

如需添加新的驱动，只需实现 Kode\Session\Contract\Driver 接口：

然后注册到 SessionManager（通过 extend() 注册的回调返回 Driver 实例，已可正确生效）：

许可证

Apache License 2.0 - see LICENSE