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

storageless完整API速查Configuration与SessionInterface核心方法详解【免费下载链接】storageless:mailbox_with_mail: storage-less PSR-7 session support项目地址: https://gitcode.com/gh_mirrors/st/storagelessstorageless 是一个基于 PSR-7 的无存储会话storage-less sessionPHP 库它把会话数据直接签名进 JWT 并保存在 Cookie 里彻底告别服务端 Session 存储。本文是一份面向新手的 storageless 完整 API 速查重点详解Configuration配置类与SessionInterface会话接口的核心方法帮你快速上手这套无存储会话方案。 storageless 是什么无存储会话原理速览传统 PHP 会话依赖$_SESSION与服务端存储而 storageless 的做法完全不同会话数据被序列化后写入 JWT Token再放入 Cookie默认名为__Secure-slsessionJWT 使用对称或非对称密钥签名客户端无法篡改数据服务端无需任何存储、无需粘性会话任意节点持有密钥即可校验会话这带来两个显著优势零 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方法返回值说明getJwtConfiguration()JwtConfig获取 JWT 签名/校验配置getClock()ClockInterface获取时钟默认系统时间getCookie()SetCookie获取会话 Cookie 配置getIdleTimeout()int会话空闲超时秒默认4320012 小时getRefreshTime()intToken 刷新间隔秒默认60getSessionAttribute()string会话挂载到 Request 的属性名默认sessiongetClientFingerprintConfiguration()FingerprintConfig客户端指纹防会话劫持配置修改方法速查表With 系列方法用途withJwtConfiguration(JwtConfig $c)更换签名算法或密钥withClock(ClockInterface $c)注入自定义时钟测试常用withCookie(SetCookie $c)自定义 Cookie 名称、Secure、HttpOnly 等withIdleTimeout(int $sec)调整会话空闲过期时间withRefreshTime(int $sec)调整 Token 自动续期间隔withSessionAttribute(string $name)修改 Request 中的会话属性名withClientFingerprintConfiguration(FingerprintConfig $f)开启 IP User-Agent 指纹校验默认值速览 Cookie 名__Secure-slsessionSecureHttpOnlySameSiteLax空闲超时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.phpLazySession惰性加载包装器只有真正访问会话时才解析 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-Agentuse 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考