Download the PHP package veasin/ff-web without Composer

ff-web

ff 的 Web 中间件集合——CORS、CSRF、Gzip、JSON、日志、限流、静态文件服务、认证（Basic/Token/JWT/API Key）。

user($data, $storage) — 用户凭证管理

统一凭证生命周期管理：记录、读取、检测、销毁用户凭证。支持多个独立 storage（default / session / token / jwt）。

容器配置——storage 需注册 #user.{name}，包含五个回调：

user\session() — Session 凭证 storage

基于 PHP 原生 session 的凭证存储，零外部依赖。token 返回 session_id()，数据存储在 $_SESSION['#user']。

user\token($provider, $ttl, $prefix) — Token 凭证 storage

通过 $provider 回调接入 Redis/APCu/DB 等任意存储后端。自动从 Authorization: Bearer 头提取 token，生成 64 位随机 hex token。

参数：

• $provider: callable 必填 存储回调，签名：
  • 'get' → fn(string $key): ?string — 读
  • 'set' → fn(string $key, string $data, ?int $ttl): void — 写
  • 'del' → fn(string $key): void — 删
• $ttl: int 默认 86400 token 过期秒数
• $prefix: string 默认 'ff_ut:' token 存储 key 前缀

user\jwt($secret, $ttl, $algo) — JWT 凭证 storage

纯 PHP 实现 HS256 JWT，零外部依赖。自动从 Authorization: Bearer 头提取 token，payload 内嵌 user 数据和 exp/iat 声明。

参数：

• $secret: string 必填 HMAC 签名密钥
• $ttl: int 默认 86400 token 过期秒数
• $algo: string 默认 'HS256' 算法，当前仅支持 HS256

所有预制中间件返回 callable，直接传入 middleware() 或 hump() 使用：

认证相关

basic(prefix, realm) — HTTP Basic 认证

从 Authorization: Basic 头提取用户名密码，调用验证器。验证器返回值直接存入 user（可返回用户对象而非 true），支持密码含冒号。

参数：

• $prefix: string 默认 '#web/auth' 容器键前缀
• $realm: ?string 默认 null WWW-Authenticate realm，null 时使用 i18n 翻译

容器配置：

• {prefix}/validators: array - 验证器数组，接收 ($user, $pass) 返回用户信息
• {prefix}/user: mixed - 认证通过后写入用户信息

token(prefix, headerName) — Token 认证

从请求头或 URL 查询参数 ?token= 提取 token，调用验证器。

参数：

• $prefix: string 默认 '#web/auth' 容器键前缀
• $headerName: string 默认 'Authorization' 请求头名称（未取到时 fallback 查询参数 token）

容器配置：

• {prefix}/validators: array - 验证器数组，接收 ($token) 返回用户信息
• {prefix}/user: mixed - 认证通过后写入用户信息

jwt(prefix, algo) — JWT 认证

从 Authorization: Bearer <token> 提取 JWT，HMAC 验证签名后解码 payload。

参数：

• $prefix: string 默认 '#web/auth' 容器键前缀
• $algo: string 默认 'HS256' 签名算法，支持 HS256、HS512

容器配置：

• {prefix}/secret: string - HMAC 签名密钥
• {prefix}/validators: array - 验证器数组，接收 ($payload) 返回用户信息
• {prefix}/user: mixed - 认证通过后写入用户信息
• {prefix}/payload: array - 自动写入解码后的 JWT payload

apikey(prefix, headerName, queryName) — API Key 认证

从请求头或 URL 查询参数提取 API Key，调用验证器。

参数：

• $prefix: string 默认 '#web/auth' 容器键前缀
• $headerName: string 默认 'X-API-Key' 请求头名称
• $queryName: string 默认 'api_key' URL 查询参数名

容器配置：

• {prefix}/validators: array - 验证器数组，接收 ($apiKey) 返回用户信息
• {prefix}/user: mixed - 认证通过后写入用户信息

通用中间件

cors(options) — CORS 跨域

为响应添加 CORS 头，OPTIONS 预检请求直接返回空响应。

$options：

• origin: string|array 默认 '*' 允许的源，数组时随机选取
• methods: string 默认 'GET,POST,PUT,DELETE,OPTIONS' 允许的 HTTP 方法
• headers: string 默认 'Content-Type,Authorization,X-CSRF-Token' 允许的请求头
• credentials: bool 默认 false 是否允许发送凭证
• max-age: int 默认 86400 预检缓存时间（秒）

csrf(verify) — CSRF 防护

• verify: false（默认）：生成 token 注入响应（数组加 _token 字段，对象加 token 属性）
• verify: true：校验请求中的 _token 或 X-CSRF-Token 头，不匹配返回 419

容器配置：

• #web/csrf/token: string - 存储/读取当前会话的 CSRF token

error(statusMap) — 异常处理

捕获所有 \Throwable 异常，根据异常类型映射状态码和 HTTP 状态描述（reason phrase）。不输出 body，错误信息通过 output(..., ['message' => ...]) 写入 HTTP 响应头（如 HTTP/1.1 400 Invalid argument）。未匹配的异常返回 500 且状态描述为空。

int 值只设置状态码，HTTP 状态描述为空。[int, string] 中 string 为 i18n 键或模板，支持上下文占位符：{status}、{code}、{message}、{file}、{line}。其中 {message} 直接替换为 $e->getMessage()，无需预先注册翻译。

未配置消息时自动回退到 container("#web/error/$code") 查找，存在则过 i18n，不存在则状态描述为空：

参数：

• $statusMap: array 默认 [] 异常类名映射，值为 int（仅状态码）或 [int, ?string]（状态码 + i18n 键或模板，支持 {message} 等占位符）

gzip(level) — Gzip 响应压缩

检查客户端 Accept-Encoding: gzip，压缩后内容比原内容小时启用压缩。自动跳过 null、array、OPTIONS 请求。

参数：

• $level: int 默认 6 压缩级别 1-9

json(pretty) — JSON 格式化

将返回值转为 JSON 输出（Content-Type 由 ff 的 json type handler 自动设置）。

参数：

• $pretty: bool 默认 false 是否格式化输出

log(level) — 请求日志

记录请求方法、URI、状态码、耗时（ms）、内存（KB）。

参数：

• $level: string 默认 'info' 日志级别

容器配置：

• #out.op: array - 读取输出操作的元数据，[1]['code'] 为响应状态码

rate(maxRequests, windowSeconds, key) — 接口限流

基于滑动窗口的 IP + 路由级别限流，默认使用 APCu 存储。

参数：

• $maxRequests: int 默认 60 时间窗口内最大请求数
• $windowSeconds: int 默认 60 时间窗口大小（秒）
• $key: string 默认 'rate' 限流键名前缀

容器配置：

• #web/rate/storage: callable - 自定义存储，签名 fn($key) => [...]（读取）或 fn($key, $value, $ttl) => 1（写入）

serve(root, cache) — 静态文件服务

根据 URI 在指定目录查找静态文件，自动设置 MIME 类型。目录自动追加 index.html。

参数：

• $root: string 必填 静态文件根目录
• $cache: null|false|int|string|array 默认 null 缓存策略
  • null（默认）— 不输出 Cache-Control，浏览器自行决定
  • false — Cache-Control: no-cache, no-store, must-revalidate
  • 3600 / 86400 — Cache-Control: public, max-age=N
  • 'etag' — ETag 条件缓存（filemtime+filesize 快速计算），命中返回 304
  • 'modified' — Last-Modified 条件缓存，命中返回 304
  • ['control' => 'etag,modified', 'age' => 3600] — 组合策略，control 逗号分隔，age 为 max-age 秒数

优先级：显式传参 > container('#web/static/cache') > 默认无缓存

内置 MIME 类型支持：html、htm、txt、css、js、json、png、jpg、jpeg、gif、svg、ico、woff、woff2、ttf、zip、xml

容器配置：

• #web/static/mimes: array - 扩展 MIME 类型
• #web/static/cache: null|false|int|string|array - 全局默认缓存策略，参数未传时回退到此配置