storageless完整API速查：Configuration与SessionInterface核心方法详解

storageless完整API速查：Configuration与SessionInterface核心方法详解

【免费下载链接】storageless:mailbox_with_mail: storage-less PSR-7 session support项目地址: https://gitcode.com/gh_mirrors/st/storageless

storageless 是一个基于 PSR-7 的无存储会话（storage-less session）PHP 库，它把会话数据直接签名进 JWT 并保存在 Cookie 里，彻底告别服务端 Session 存储。本文是一份面向新手的 storageless 完整 API 速查，重点详解Configuration配置类与SessionInterface会话接口的核心方法，帮你快速上手这套无存储会话方案。

📌 storageless 是什么？无存储会话原理速览

传统 PHP 会话依赖$_SESSION与服务端存储，而 storageless 的做法完全不同：

• 会话数据被序列化后写入 JWT Token，再放入 Cookie（默认名为__Secure-slsession）
• JWT 使用对称或非对称密钥签名，客户端无法篡改数据
• 服务端无需任何存储、无需粘性会话，任意节点持有密钥即可校验会话

这带来两个显著优势：零 I/O（不再读写 Session 文件或数据库）和天然支持水平扩展。官方建议会话数据控制在 400 字节以内，且内容应允许客户端可读（因为 JWT 默认只签名、不加密）。

核心源码参考：src/Storageless/Session/、src/Storageless/Http/SessionMiddleware.php

⚙️ storageless Configuration 核心方法详解

PSR7Sessions\Storageless\Http\Configuration是 storageless 的配置中心，位于 src/Storageless/Http/Configuration.php。它采用不可变设计：所有with*方法都会返回新的实例，不会修改原对象。

构造入口：fromJwtConfiguration()

这是最常用的工厂方法，只需传入lcobucci/jwt的配置即可：

use Lcobucci\JWT\Configuration as JwtConfig; use Lcobucci\JWT\Signer\Hmac\Sha256; use Lcobucci\JWT\Signer\Key\InMemory; use PSR7Sessions\Storageless\Http\Configuration; use PSR7Sessions\Storageless\Http\SessionMiddleware; $sessionMiddleware = new SessionMiddleware( Configuration::fromJwtConfiguration( JwtConfig::forSymmetricSigner( new Sha256(), InMemory::base64Encoded('替换成你自己的高熵密钥'), ) ) );

读取方法速查表（Getter）

修改方法速查表（With 系列）

默认值速览 🎯

• Cookie 名：__Secure-slsession（Secure+HttpOnly+SameSite=Lax）
• 空闲超时：43200 秒（12 小时）
• Token 刷新：每 60 秒
• 本地开发时请用withCookie()关闭 Secure 标记，详见 docs/configuration.md

🔑 storageless SessionInterface 核心方法详解

SessionInterface是所有会话对象的统一接口，位于 src/Storageless/Session/SessionInterface.php。它继承自JsonSerializable，方法非常精简。

八个核心方法一览

interface SessionInterface extends JsonSerializable { public function set(string $key, $value): void; // 写入数据 public function get(string $key, $default = null); // 读取数据 public function remove(string $key): void; // 删除单个键 public function clear(): void; // 清空会话 public function has(string $key): bool; // 键是否存在 public function hasChanged(): bool; // 会话是否被修改过 public function isEmpty(): bool; // 会话是否为空 public function jsonSerialize(): object; // 序列化为对象 }

使用技巧 📝

• get()的默认值：键不存在时返回$default（会被转换成可安全存储的标量或数组）
• hasChanged()很关键：中间件靠它判断是否需要重新签发 Cookie。若会话被清空（isEmpty()为 true），会直接下发过期 Cookie 实现注销
• set()的值类型：支持标量、数组、对象或JsonSerializable，内部通过 JSON 编码统一转换成标量与数组

两个重要实现类

• DefaultSessionData：默认实现，通过newEmptySession()、fromDecodedTokenData()等静态方法创建，见 src/Storageless/Session/DefaultSessionData.php
• LazySession：惰性加载包装器，只有真正访问会话时才解析 JWT，提升性能，见 src/Storageless/Session/LazySession.php

🚀 实战：10 秒接入 PSR-7 中间件

在任意 PSR-15 兼容应用中，通过SessionMiddleware即可获得会话能力：

use Psr\Http\Message\ServerRequestInterface; use Psr\Http\Message\ResponseInterface; $app->get('/counter', function (ServerRequestInterface $request, ResponseInterface $response) { $session = $request->getAttribute(SessionMiddleware::SESSION_ATTRIBUTE); $count = $session->get('counter', 0) + 1; $session->set('counter', $count); $response->getBody()->write('访问次数：' . $count); return $response; });

要点：通过SessionMiddleware::SESSION_ATTRIBUTE（即session）从 Request 属性中取出会话对象，读写即可，中间件会自动完成 JWT 签发、校验与续期。完整可运行示例见 examples/index.php。

🛡️ 安全增强：客户端指纹绑定

为防止 Cookie 被盗导致的会话劫持，可绑定客户端 IP 与 User-Agent：

use PSR7Sessions\Storageless\Http\ClientFingerprint\Configuration as FingerprintConfig; $config = Configuration::fromJwtConfiguration(/* ... */) ->withClientFingerprintConfiguration( FingerprintConfig::forIpAndUserAgent() );

反向代理场景下可自定义Source接口实现，提取X-Real-IP等头部，参考 src/Storageless/Http/ClientFingerprint/。

💡 常见问题与注意事项

• 会话数据会暴露给客户端：JWT 只签名不加密，请勿存放敏感信息
• Cookie 体积限制：建议会话小于 400 字节，避免超出浏览器 Cookie 上限
• 本地开发：默认 Cookie 带__Secure-前缀且要求 HTTPS，本地调试需用withCookie()调整
• 局限性清单：更多边界情况可查阅 docs/limitations.md

✅ 总结

storageless 用一套非常精简的 API 就实现了完整的无存储会话能力：Configuration负责全部配置（签名、Cookie、超时、指纹），SessionInterface提供八个直观的读写方法，配合SessionMiddleware即可无缝融入 PSR-7/PSR-15 应用。希望这份 storageless 完整 API 速查能成为你日常开发中的随身手册 🗂️

【免费下载链接】storageless:mailbox_with_mail: storage-less PSR-7 session support项目地址: https://gitcode.com/gh_mirrors/st/storageless