Download the PHP package kode/jwt without Composer

Kode JWT：一个健壮、全面、现代化的 PHP 8.3+ JWT 包

项目名称：kode/jwt
当前版本：v1.12.0
目标：为现代 PHP 应用提供安全、灵活、高性能的 JWT 身份验证解决方案，支持单点登录（SSO）、多点登录、黑名单管理、自动续期、多平台适配、防重放攻击（Anti-Replay）、JWK 密钥管理、Token 客户端指纹绑定、JWKS 端点发布、Token Introspection、OIDC Discovery，兼容 FPM、Swoole、RoadRunner 等运行环境。

📌 项目愿景

构建一个生产级、零侵入、高可扩展的 JWT 包，专为 PHP 8.3+ 设计，充分利用现代 PHP 特性（readonly class、类型化类常量、json_validate()、#[\Override] 属性、enum、联合类型、反射优化），并支持主流框架（Laravel、Symfony、ThinkPHP、Hyperf、EasySwoole 等）无缝接入。 可使用 kode 相关包或其他通用适合的包快速集成。

🚀 核心特性

📁 项目结构（PSR-4）

🛠️ 安装方式

CLI 工具初始化

安装完成后，在你的项目根目录运行以下命令来生成配置文件和密钥：

CLI 命令详解

install 命令选项

key 命令选项

示例：

生成的文件结构

运行 php jwt install 后，会在你的项目目录中生成以下文件：

重要：请确保 storage/keys/ 目录不在版本控制中（添加到 .gitignore），以保护密钥安全。

🧩 配置文件（config/jwt.php）

运行 php jwt install 后，会自动生成配置文件。以下是完整配置说明：

🔐 核心类设计（示例）

Token/Payload.php

Payload增强功能详解

Payload类现在支持更灵活的自定义数据处理和更健壮的方法实现：

1. 灵活的自定义数据处理

Payload类提供了两种方式来处理自定义数据：

使用create()静态方法（推荐）

使用fromArray()方法

2. 增强的方法实现

Payload类提供了丰富的方法来操作和检查Payload数据：

自定义数据操作方法

角色和权限检查方法

其他实用方法

Guard/SsoGuard.php（单点登录）

Storage/RedisStorage.php（协程安全）

🧪 使用示例（Laravel / Hyperf）

1. 生成 Token

2. 验证 Token

3. 刷新 Token

4. 注销 Token（黑名单管理）

被「注销 / 封禁 / 撤销」的 Token 会将其 jti 写入黑名单，后续在 Guard 鉴权、Introspection、isTokenValid 中都会立即判定为失效。

上述方法均支持可选的 $guard 参数（传 null 使用默认守卫），自动路由到该守卫对应的存储后端。

5. 使用便捷方法

⚠️ KodeJwt::builder() 不可跨请求共享（Builder 是可变对象） KodeJwt::builder() 每次调用都返回全新实例，因此以下两种用法都是安全的：

切勿把 KodeJwt::builder() 的返回值存为全局/静态单例并在多次签发间复用，否则会出现 claims 泄漏与前次 jti 碰撞。 生产环境签发更推荐 KodeJwt::guard($g)->issue(new Payload(...))，由 Guard 内部管理独立实例。

// 获取用户的所有活跃Token $tokens = KodeJwt::getUserTokens('123', 'app');

// 强制注销用户的所有Token $count = KodeJwt::revokeUserTokens('123', 'app');

// 检查Token是否有效 $isValid = KodeJwt::isTokenValid($token);

// 获取Token详细信息 $info = KodeJwt::getTokenInfo($token); // 返回: ['uid' => 123, 'platform' => 'app', 'exp' => 1234567890, ...]

// 清理过期的Token $cleanedCount = KodeJwt::cleanExpired();

// 获取存储统计信息 $stats = KodeJwt::getStats(); // 返回: ['total' => 100, 'expired' => 20, 'active' => 80]

// 使用增强的Payload创建方法 // 1. 使用数组自定义数据 $payload = Payload::create( uid: 456, username: 'janedoe', platform: 'web', exp: time() + 86400, iat: time(), jti: uniqid('jwt'), roles: ['user'], perms: ['read', 'write'], customData: [ 'department' => 'Marketing', 'level' => 3, 'preferences' => [ 'theme' => 'dark', 'language' => 'zh-CN' ] ] );

// 2. 使用加密字符串自定义数据 $encryptedData = base64_encode(json_encode([ 'sensitive_info' => 'secret_data', 'timestamp' => time() ]));

$payload = Payload::create( uid: 789, username: 'bobsmith', platform: 'mobile', exp: time() + 86400, iat: time(), jti: uniqid('jwt'), customData: $encryptedData );

┌─────────────────────────────────────────────────────────┐ │ 防御层 1：永久禁用 "none" 算法 │ │ 即使配置允许，"none" 也直接拒绝 │ ├─────────────────────────────────────────────────────────┤ │ 防御层 2：显式白名单（allowed_algorithms 数组） │ │ 适用于密钥轮换、多算法并存场景 │ │ Token alg 必须命中白名单 │ ├─────────────────────────────────────────────────────────┤ │ 防御层 3：单算法严格匹配（algo 单值） │ │ 适用于单算法场景 │ │ Token alg 必须与配置 algo 严格相等 │ └─────────────────────────────────────────────────────────┘

攻击者构造：alg=HS256，用服务端 RS256 公钥当 HMAC 密钥签名 ↓ 防御层 3 触发：Token alg=HS256 ≠ 配置 algo=RS256 → 拒绝 防御层 2 触发：HS256 不在 allowed_algorithms=[RS256, RS384] 中 → 拒绝

[客户端] ——A: 请求 (Token: eyJ...)→ [服务器] ↓ (Token 被截获) [攻击者] ——B: 重复使用 Token eyJ...→ [服务器]

[1] 解析 Token → 取出 jti、nonce [2] Redis EVAL "SET NX" → 首次消费返回 1，重放返回 0 [3] 命中重放 → 抛出 TokenReplayException json // phpstan.neon parameters: level: 12 paths:

• src bash

  生成 Token

  php bin/jwt token generate --uid=123 --username=john --platform=web

验证 Token

php bin/jwt token verify --token=eyJ...

刷新 Token

php bin/jwt token refresh --token=eyJ...

注销 Token

php bin/jwt token invalidate --token=eyJ...

查看 Token 信息

php bin/jwt token info --token=eyJ... bash

安装依赖

composer require kode/jwt

发布配置文件（会生成 config/jwt.php）

php artisan jwt:install

生成密钥

php artisan jwt:key bash composer require kode/jwt bash composer require kode/jwt bash composer require kode/jwt yaml jwt: defaults: guard: api storage: redis guards: api: driver: sso storage: redis algo: RS256 public_key: '%kernel.project_dir%/var/keys/public.pem' private_key: '%kernel.project_dir%/var/keys/private.pem' ttl: 3600 refresh_ttl: 604800 storage: redis: host: 127.0.0.1 port: 6379 prefix: 'kode:jwt:' yaml services: Kode\Jwt\KodeJwt: class: Kode\Jwt\KodeJwt calls:

• method: detectAndLoadConfig

  App\Security\JwtAuthenticator: arguments: $jwtService: '@Kode\Jwt\KodeJwt' bash composer require kode/jwt bash php yii jwt/init bash composer require kode/jwt bash bin/cake jwt bash

  下载并解压包后

  php bin/jwt install --config-only php bin/jwt key rsa --force

📖 API 参考

KodeJwt 门面类

KodeJwt 是包的主入口点，提供静态方法访问所有功能。

初始化与配置

获取守卫实例

⚠️ 严格验证：自 v1.12.1 起，KodeJwt::guard($name) 会在创建 Guard 实例前验证 $name 是否在配置的 guards 中。若请求的 Guard 未配置（且非默认 'api'），将抛出 JwtException: Guard [name] is not configured. Available guards: api，防止因配置缺失导致的 silent fallback 风险。

Token 操作方法

用户 Token 管理

存储操作

防重放保护（v1.8.0+）

密钥生成

事件系统

Payload 类

Payload 类用于构建和管理 JWT Payload。

创建 Payload

Payload 属性

Payload 方法

Guard 接口

Storage 接口

事件类

TokenIssued

TokenExpired

TokenRevoked

异常类

📚 最佳实践

1. 密钥管理

2. 多守卫配置

3. 事件监听

4. 错误处理

🔧 扩展指南

自定义存储驱动

注册自定义驱动：

自定义守卫

📦 依赖与兼容性

必需依赖

• PHP >= 8.3
• ext-json
• ext-openssl

可选依赖

• ext-redis：Redis 存储驱动
• ext-apcu：APCu 存储驱动
• ext-memcached：Memcached 存储驱动
• ext-pdo：数据库存储驱动
• ext-swoole：Swoole 协程支持

兼容环境

• PHP-FPM
• Swoole
• RoadRunner
• ReactPHP
• Amp