README

JSON Web Token（RFC 7519）编解码器，零框架依赖的纯库实现（仅依赖 ext-json 与 ext-openssl）。支持 HS256/HS384/HS512 对称密钥与 RS256/RS384/RS512 非对称密钥，内置 exp/nbf/iss/aud 声明校验与时钟偏差容忍。

环境要求

PHP >= 8.3
ext-json
ext-openssl（RS 系列算法签名需要）

安装

composer require fiberphp/jwt

快速开始

HS256 对称密钥

use FiberPHP\Jwt\Jwt;

$jwt = new Jwt('your-secret-key', 'HS256');

// 签发 Token（默认 1 小时过期）
$token = $jwt->encode([
    'sub'   => 'user-1',
    'name'  => '张三',
    'admin' => true,
], 3600);

// 解码并验证（签名 + 过期 + nbf + iss + aud）
$payload = $jwt->decode($token);

RS256 非对称密钥

$jwt = new Jwt(
    secretOrPrivateKey: $privateKeyPem,   // 签发时使用私钥
    algorithm: 'RS256',
    publicKey: $publicKeyPem,              // 验证时使用公钥
);

$token = $jwt->encode(['sub' => 'user-1'], 3600);
$payload = $jwt->decode($token);

配置说明

Jwt 构造参数：

参数	默认值	说明
`secretOrPrivateKey`	必填	HS 为 secret string，RS 为 PEM 私钥
`algorithm`	`HS256`	签名算法：HS256/HS384/HS512/RS256/RS384/RS512
`publicKey`	null	PEM 公钥，仅 RS 验证时需要
`issuer`	null	默认签发者（iss），encode 时注入、decode 时校验
`audience`	null	默认受众（aud），encode 时注入、decode 时校验
`leeway`	0	时钟偏差容忍（秒），用于 exp/nbf 校验

encode($payload, $ttl, $header) 中 ttl：>0 写入 exp；=0 永不过期；<0 立即过期（负偏移）。

特性

能力	说明
双算法族	HMAC-SHA2 对称 / RSA-SHA2 非对称
防算法混淆	解码时强制校验 header.alg 与实例算法一致，拒绝 `none`
标准声明	自动注入 iat/iss/aud，校验 exp/nbf/iss/aud
时钟容忍	`leeway` 防止分布式时钟偏差导致误判
Base64URL	标准 URL 安全编码，无填充
不安全解码	`decodeUnverified` 仅读 payload，用于调试（勿用于生产）

错误处理

所有验证失败均抛出 FiberPHP\Jwt\Exception\JwtException（继承 RuntimeException），异常携带机器可读的 reason 标识：

reason	场景
`format`	三段格式错误、Base64URL/header/payload 解析失败
`algorithm`	算法不受支持，或 token header.alg 与实例不一致
`signature`	签名验证失败、RSA 验签未配置 publicKey
`expired`	已超过 exp（可用 `isExpired()` 判断）
`not_before`	当前时间早于 nbf
`issuer`	iss 不匹配
`audience`	aud 不匹配
`encode`	编码失败（如声明含非法 UTF-8）

use FiberPHP\Jwt\Exception\JwtException;

try {
    $payload = $jwt->decode($token);
} catch (JwtException $e) {
    // 按 getReason() 分支处理，例如 expired 时触发刷新 Token
    http_response_code(401);
}

decodeUnverified() 不校验签名与有效期，仅格式错误时抛异常，禁止用于生产鉴权。

fiberphp / jwt

Package info

Security

Statistics