Download the PHP package kode/jwt without Composer

On this page you can find all versions of the php package kode/jwt. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of kode/jwt

Informations about the package jwt

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

项目名称：kode/jwt
当前版本：v1.10.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 相关包或其他通用适合的包快速集成。

🚀 核心特性

特性 说明
✅ PHP 8.3+ 原生支持 使用 readonly class、类型化类常量（private const array FOO = [...]）、json_validate()、#[\Override] 属性等 PHP 8.3+ 特性
✅ 多平台支持 H5、PC、App、小程序（微信/支付宝/抖音）等，通过 platform 声明区分，是否启用平台，平台配置一致或单独配置
✅ 单点登录（SSO） 同一用户在同一平台仅允许一个有效 Token，支持 Redis Lua 原子化踢出
✅ 多点登录（MLO） 支持同一用户在多个设备同时登录
✅ Token 黑名单 支持主动注销、强制下线，基于 Redis 或内存存储（协程安全）
✅ 自动续期（Refresh） 支持滑动过期、固定刷新周期，防止频繁登录
✅ 多环境配置 支持 config/jwt.php 配置，兼容 Laravel、Hyperf 等框架
✅ 运行时兼容 支持 FPM、Swoole 多进程/协程、RoadRunner 多线程
✅ 类型安全 & 反射优化 使用 ReflectionClass + 缓存实现高性能依赖注入与配置解析
✅ 逆变/协变设计 接口设计遵循 LSP，支持泛型风格扩展（通过 PHPDoc + 命名规范）
✅ 零框架依赖 可独立使用，也可通过适配器接入任意框架
✅ 事件驱动 提供 TokenIssued、TokenExpired、TokenRevoked 等事件钩子
✅ 审计日志 可选记录 Token 生成、使用、注销行为，使用通用日志包
✅ 加密算法可插拔 默认 HS256 / RS256，支持自定义签名器
✅ 防重放攻击（Anti-Replay） 基于 Redis Nonce + 滑动窗口，杜绝 Token 被截获后重复使用
✅ 高熵 JTI 32 字节（256 bit）密码学安全随机数，远高于 UUID v4
✅ 标准声明（iss/aud/sub） 业务级强制校验，防止跨服务/跨租户混用
✅ 时钟漂移容忍 跨节点 NTP 偏差场景下，配置 clock_skew 即可容错
✅ Redis 原子化撤销 Lua 脚本保证"黑名单 + SSO 映射 + 用户 Token 列表"三步原子性
🆕 v1.9 JWK 密钥管理（RFC 7517） Jwk / JwkSet / KeyConverter / JwkFactory，支持 RSA / EC / oct 三种密钥类型，PEM ↔ JWK 互转，CSPRNG 安全密钥生成
🆕 v1.9 Token 客户端指纹绑定 Fingerprint 组件将 Token 与客户端 UA + IP 前缀绑定，防止跨设备重放，内置可信内网 IP 白名单
🆕 v1.9 算法白名单强制校验 三层防御：永久禁用 none 算法 → 显式白名单 → 单算法严格匹配，杜绝算法混淆攻击
🆕 v1.9 PHP 8.3 readonly class Jwk、JwkSet 等核心值对象使用 final readonly class，运行期不可变，防止密钥被篡改
🆕 v1.9 类型化类常量 使用 private const array SUPPORTED_KTY = [...] 等 PHP 8.3 类型化常量，强化类型安全
🆕 v1.10 JWKS 端点发布（RFC 7517 §5） JwksPublisher 将 JWK Set 以标准 JSON 格式发布到 jwks_uri，自动剥离私钥，支持 ETag / If-None-Match 协商缓存
🆕 v1.10 Token Introspection（RFC 7662） Introspector + IntrospectionResponse 提供标准 introspection 端点，资源服务器可查询 Token 当前状态
🆕 v1.10 OIDC Discovery（RFC 8414） DiscoveryConfiguration + DiscoveryPublisher 发布授权服务器元数据，支持 /.well-known/openid-configuration
🆕 v1.10 Scope 值对象与声明检查器 Scope 不可变集合（has/hasAny/hasAll/intersect/diff），ClaimInspector 链式校验 issuer/audience/scope/time window
🆕 v1.10 TokenPolicy 策略对象 不可变策略值对象，链式配置（issuer/audience/platform/scope/custom），一次性 enforce() 完成 Token 校验

📁 项目结构（PSR-4）

🛠️ 安装方式

CLI 工具初始化

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

CLI 命令详解

命令 说明 示例
jwt install 或 jwt i 安装配置文件并生成密钥 php jwt install
jwt key 或 jwt k 生成密钥对 php jwt key rsa
jwt help 或 jwt h 显示帮助信息 php jwt help

install 命令选项

选项 说明
--config-only 仅发布配置文件，不生成密钥
--key-only 仅生成密钥，不发布配置文件
--force 强制覆盖已存在的文件
--platform=<name> 指定默认平台（默认: web）

key 命令选项

参数 说明
rsa 生成 RSA 密钥对（默认）
hmac 生成 HMAC 密钥
stdout 输出到标准输出（而非文件）
file 保存到文件（默认）
--force 强制覆盖已存在的密钥文件

示例：

生成的文件结构

运行 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（加入黑名单）

5. 使用便捷方法

🚀 快速开始（v1.10.x）

1. 最小化示例

2. 启用 Redis 存储 + 防重放

3. 自定义 Payload 并签发

4. 异常处理模板

完整示例请参考 examples/ 目录：

  • examples/basic_usage.php — 基础 + expected_claims 校验
  • examples/storage_usage.php — 多存储 + SsoStorageInterface 增强
  • examples/advanced_usage.php — 标准声明 + Nonce + 多签

🆕 v1.10.0 新特性：OAuth2 / OIDC 互操作能力增强

v1.10.0 聚焦 OAuth2 / OIDC 互操作能力增强，新增四个 RFC 标准模块：JWKS 端点发布（RFC 7517 §5）、Token Introspection（RFC 7662）、OIDC Discovery（RFC 8414）、Scope 值对象与声明检查器，并引入 TokenPolicy 策略对象统一管理 Token 校验逻辑。所有新模块均为 PSR-7 / PSR-15 解耦设计，可适配任意框架的 HTTP 层。

1. JWKS 端点发布（RFC 7517 §5）

JwksPublisher 将本地 JWK Set 以标准 JSON 格式发布到 jwks_uri，供资源服务器拉取公钥验签。

类 说明
Kode\Jwt\OAuth2\JwksPublisher JWKS 端点发布器，自动剥离私钥，支持 ETag / If-None-Match
Kode\Jwt\OAuth2\JwksResponse 与 PSR-7 解耦的响应值对象（status / headers / body）

1.1 发布公开 JWK Set

安全设计：

2. Token Introspection（RFC 7662）

Introspector 提供标准 introspection 端点，资源服务器可通过它查询 Token 当前状态。

类 说明
Kode\Jwt\OAuth2\IntrospectionResponse RFC 7662 §2.2 响应值对象，final readonly class
Kode\Jwt\OAuth2\Introspector 内省服务，自动完成解析验签 + 黑名单检查

2.1 内省 Token

信息侧通道防御：任何失败（格式错误、签名错误、过期、黑名单、平台不匹配）统一返回 {"active":false}，不向资源服务器泄露失败原因，避免攻击者通过 introspection 响应探测系统状态。

3. OIDC Discovery（RFC 8414）

DiscoveryPublisher 发布授权服务器元数据到 /.well-known/openid-configuration。

类 说明
Kode\Jwt\OpenId\DiscoveryConfiguration RFC 8414 元数据值对象，final readonly class
Kode\Jwt\OpenId\DiscoveryPublisher Discovery 端点发布器，支持 ETag 协商缓存

3.1 发布 Discovery 文档

标准路径：

4. Scope 值对象（RFC 6749 §3.3）

Scope 提供不可变集合语义，统一处理 OAuth2 / OIDC scope 的解析、校验、集合运算。

5. ClaimInspector 链式声明校验器

ClaimInspector 是无状态服务，提供链式 API 校验 Payload 声明。

常量时间比较：assertIssuer / assertPlatform / assertSubject 内部使用 hash_equals，防止时序攻击。

6. TokenPolicy 策略对象

TokenPolicy 是不可变值对象，承载完整 Token 校验策略，链式 with* 方法返回新实例。

7. KodeJwt 门面便捷方法

v1.10.0 在 KodeJwt 门面层新增 8 个便捷方法：

方法 用途
KodeJwt::jwksPublisher(JwkSet, maxAge) 创建 JWKS 端点发布器
KodeJwt::introspector(guard) 创建 Introspector
KodeJwt::introspect(token, platform, clientId, guard) 便捷内省
KodeJwt::discoveryConfiguration(issuer, ...) 创建 Discovery 配置
KodeJwt::discoveryPublisher(config, maxAge) 创建 Discovery 端点发布器
KodeJwt::tokenPolicy() 创建空 Token 策略
KodeJwt::claimInspector() 创建 Claim 检查器
KodeJwt::scope(string) 从字符串创建 Scope 值对象

8. 测试与质量

🆕 v1.9.0 新特性：PHP 8.3+ + JWK 模块 + Token 指纹 + 算法白名单

v1.9.0 是一次主版本升级，将最低 PHP 版本提升至 8.3+，引入 JWK 密钥管理、Token 客户端指纹绑定、算法白名单三层防御，并全面应用 PHP 8.3 现代化特性。

1. JWK 密钥管理模块（RFC 7517 / RFC 7518）

新增 src/Key/ 目录，提供完整的 JWK 工作流：

类 说明
Jwk final readonly class 值对象，表示一个 JWK，支持 RSA / EC / oct 三种 kty
JwkSet JWK 集合，用于密钥轮换场景下按 kid 选择密钥
KeyConverter PEM ↔ JWK 互转，包含 ASN.1 DER 编码实现 RSA SubjectPublicKeyInfo 构造
JwkFactory CSPRNG 安全密钥生成（random_bytes），RSA 默认 2048 位（NIST SP 800-131A）

1.1 生成对称密钥（oct）

1.2 生成 RSA 密钥对

1.3 PEM ↔ JWK 互转

1.4 JWK Set 与密钥选择

1.5 安全设计要点

2. Token 客户端指纹绑定（Fingerprint）

新增 src/Security/Fingerprint.php，将 Token 与客户端环境（UA + IP 前缀）绑定，防止：

2.1 基本用法

2.2 安全策略

3. 算法白名单三层防御

Parser::ensureAllowedAlgorithm() 强化算法校验，杜绝算法混淆攻击（Algorithm Confusion Attack）：

配置示例

攻击场景示例

4. PHP 8.3 现代化特性全面应用

特性 应用位置 说明
readonly class Jwk、JwkSet 整个类不可变，构造后任何属性不可修改
类型化类常量 Jwk::SUPPORTED_KTY、JwkFactory::ALG_KEY_BYTES、Fingerprint::DEFAULT_FIELDS 等 private const array FOO = [...] 强化类型安全
json_validate() Jwk::fromJson() 替代 json_decode + json_last_error 检查的繁琐写法
#[\Override] 属性 Jwk::toArray()、Jwk::toJson()、Jwk::__toString() 显式声明方法重写，防止子类意外覆盖

5. v1.9.0 其他重要改进

6. 测试覆盖

v1.9.0 测试套件：145 个测试，413 个断言，新增测试覆盖：

回归测试：

🆕 v1.8.2 优化：存储驱动全面补齐 + 安全加固

v1.8.2 聚焦于接口完整性、安全加固、性能优化，修复了多个 P0/P1 级别问题。

存储驱动接口补齐

v1.8.1 中 ApcuStorage、DatabaseStorage、CoroutineRedisStorage、MemcachedStorage 缺少 touch/getRemainingTtl/clear 方法，调用会触发致命错误。v1.8.2 已全部补齐：

存储驱动 touch getRemainingTtl clear SsoStorageInterface
RedisStorage ✅ ✅ ✅ ✅
MemoryStorage ✅ ✅ ✅ ✅
FileStorage ✅ ✅ ✅ ✅
NullStorage ✅ ✅ ✅ ✅
ApcuStorage ✅ 新增 ✅ 新增 ✅ 新增 ✅ 新增
DatabaseStorage ✅ 新增 ✅ 新增 ✅ 新增 ✅ 新增
CoroutineRedisStorage ✅ 新增 ✅ 新增 ✅ 新增 ✅ 新增
MemcachedStorage ✅ 新增 ✅ 新增 ✅ 新增 ✅ 新增

安全加固

性能优化

DatabaseStorage SQL 方言自动适配

v1.8.2 之前 DatabaseStorage 硬编码 SQLite 方言（AUTOINCREMENT、INSERT OR REPLACE、strftime），但默认 DSN 是 MySQL，导致 MySQL 下不可用。现已根据 DSN 自动检测驱动类型：

MemcachedStorage addServers 修复

v1.8.2 修复了 addServers 参数结构 Bug：配置中的关联数组（['host' => ..., 'port' => ..., 'weight' => ...]）现在会自动转换为索引数组（[$host, $port, $weight]）。

全局 declare(strict_types=1)

以下文件补充了 declare(strict_types=1);，符合 PSR-12 规范：

TokenManager、StorageFactory、GuardInterface、FileStorage、NullStorage、ApcuStorage、DatabaseStorage、CoroutineRedisStorage、MemcachedStorage、RedisStorage

🆕 v1.8.1 新特性：SsoStorageInterface 能力探测

v1.8.1 引入了 Kode\Jwt\Contract\SsoStorageInterface，用于描述存储后端的"高级 SSO 能力"。

接口契约

业务代码推荐写法

已实现 SsoStorageInterface 的存储

存储 实现方式 适用场景
RedisStorage Lua 脚本（LUA_ATOMIC_REVOKE） 生产环境首选，原子性最强
CoroutineRedisStorage 协程 Redis + Lua Swoole 等协程环境
MemoryStorage 顺序执行（PHP-FPM 单进程语义） 单机测试、本地开发
FileStorage 顺序执行（文件锁语义） 单机持久化场景

关于不可变 Payload 的说明：v1.8.1 起，Payload 为 readonly 类， setEncryptedData() 改为返回新实例而非修改原实例， 调用方式：$newPayload = $payload->setEncryptedData('...')。

⚙️ 多运行时支持

环境 支持 说明
PHP-FPM ✅ 使用 Redis 或数据库存储黑名单
Swoole 协程 ✅ 使用 Swoole\Coroutine\Redis，避免连接泄露
RoadRunner ✅ 配合 spiral/roadrunner-jobs 实现异步清理

🔍 安全与性能优化

🛡️ Redis 黑名单与防重放（v1.8.0+）

核心目标：在传统的 JTI 黑名单之上，引入 Nonce 一次性消费与滑动窗口机制， 形成"两层防御"——既能在注销后立即拦截，又能在 Token 有效期内阻断重放。

1. Redis 黑名单策略

kode/jwt 默认将 storage 设为 redis，通过以下键完成 Token 生命周期管理：

键名 用途 生命周期
kode:jwt:blacklist:{jti} 注销/封禁的 JTI 集合 exp + refresh_ttl
kode:jwt:token:{jti} Token 详细快照（uid、平台、过期时间等） exp - now
kode:jwt:sso:{uid}:{platform} SSO 平台→JTI 映射 exp + refresh_ttl
kode:jwt:user:{uid}:{platform}:tokens 用户活跃 Token 列表（最近 50 条） exp + refresh_ttl
kode:jwt:replay:nonce:{jti}:{nonce} 防重放 Nonce 一次性消费标记 exp - now
kode:jwt:replay:window:{jti} 滑动窗口访问轨迹（ZSet） 窗口大小

1.1 启用 Redis 存储

1.2 主动注销（踢下线）

在 SSO 模式下，新用户登录会自动调用 atomicRevoke Lua 脚本， 一次性清理旧 Token 的黑名单、SSO 映射、用户列表、Token 详情四个键， 避免"半撤销"状态导致的并发漏洞。

2. 防重放攻击（Anti-Replay）

2.1 攻击场景

仅依赖 JTI 黑名单无法应对以下两种情况：

  1. 注销前的"中间人重放"：Token 还在有效期内，被攻击者重发。
  2. 高频试探：攻击者在短时间内用同一 Token 暴力请求敏感接口。

2.2 Nonce 一次性消费

启用后，签发 Token 时会自动注入 nonce 字段：

验证流程：

2.3 滑动窗口频率限制

当 mode = lenient 时启用，可识别异常短时间高频重放：

底层使用 Redis ZSet 维护"最近 N 秒的 Nonce 时间序列"， 过期窗口外的记录自动被裁剪。

2.4 异常处理

3. 标准声明（iss / aud / sub）强制校验

服务端验证流程会自动比对：

4. 时钟漂移容忍

适用于多节点部署、NTP 同步存在偏差的场景， 避免由于本地时间略快/略慢导致的 nbf、exp 误判。

5. 密钥管理建议

🧩 扩展建议（IDE 友好）

1. 使用 PHPStan / Psalm 进行静态分析

2. IDE Helper（生成 ide-helper.php）

🚀 高级特性

JWT 多签（Detached Signature）

支持多个签名者对同一 Payload 进行签名，适用于多方信任场景：

OpenID Connect 支持

集成 OpenID Connect 协议，支持 ID Token 生成和用户信息管理：

OAuth2 混合模式

支持 JWT 与 OAuth2 授权流程的混合使用：

JWT 密钥轮换机制

支持密钥平滑过渡，旧密钥在过渡期内仍可用于验证：

Prometheus 监控指标

提供 Token 相关的监控指标，便于集成 Prometheus：

CLI Token 管理

通过命令行管理 Token：

🤝 贡献与反馈

欢迎提交 Issue 或 PR！
GitHub: https://github.com/kode-php/jwt

命名原则：避免与 PHP 原生 jwt_* 函数冲突，使用 KodeJwt 前缀，类名清晰表达职责，方法名动词开头（issue, authenticate, refresh, invalidate）。

逆变/协变示例：
StorageInterface 作为协变返回类型，GuardInterface 可接收更具体的 Payload 子类（通过泛型模拟）。

🎯 目标达成： ---

🛠️ 框架集成指南

Laravel 集成

1. 安装配置

2. 配置说明

config/jwt.php:

3. 服务提供者注册

app/Providers/JwtServiceProvider.php:

4. 中间件使用

app/Http/Middleware/JwtAuthMiddleware.php:

注册中间件：

5. 控制器中使用

路由定义：

Hyperf 集成

1. 安装配置

2. 配置文件

config/autoload/jwt.php:

3. 协程安全的使用方式

4. 中间件

app/Middleware/JwtAuthMiddleware.php:

注册中间件：

ThinkPHP 集成

1. 安装配置

2. 配置文件

config/jwt.php:

3. 基础控制器

app/base/AuthController.php:

4. 控制器中使用

app/controller/Auth.php:

路由定义：

原生 PHP 集成

即使不使用框架，也可以轻松使用 kode/jwt：

Symfony 集成

1. 安装配置

2. 配置文件

config/packages/jwt.yaml:

3. 服务配置

config/services.yaml:

4. 自定义认证器

src/Security/JwtAuthenticator.php:

Yii2 集成

1. 安装配置

2. 配置文件

config/main.php:

3. 生成密钥脚本

commands/JwtController.php:

运行命令：

4. 行为类实现

components/AuthenticatedBehavior.php:

5. 控制器使用示例

controllers/ApiController.php:

CakePHP 集成

1. 安装配置

2. 配置文件

config/jwt.php:

在 config/bootstrap.php 中加载配置：

3. Shell 任务生成密钥

src/Shell/JwtShell.php:

运行命令：

4. 中间件实现

src/Middleware/JwtAuthenticationMiddleware.php:

在 src/Application.php 中注册中间件：

5. 控制器使用示例

src/Controller/AuthController.php:

6. 组件封装

src/Controller/Component/JwtComponent.php:

在控制器中使用组件：

使用 CLI独立 工具

即使不通过 Composer 安装，也可以使用 CLI 工具：

📖 API 参考

KodeJwt 门面类

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

初始化与配置

获取守卫实例

Token 操作方法

用户 Token 管理

存储操作

防重放保护（v1.8.0+）

密钥生成

事件系统

Payload 类

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

创建 Payload

Payload 属性

属性 类型 说明
uid int\|string\|null 用户 ID
username string\|null 用户名
platform string 平台标识
exp int 过期时间戳
iat int 签发时间戳
jti string JWT ID（唯一标识）
roles array\|null 用户角色
perms array\|null 用户权限
custom array 自定义数据
nonce string\|null 🆕 一次性随机值（防重放）
audience string\|array\|null 🆕 受众（aud）
issuer string\|null 🆕 签发者（iss）
subject string\|null 🆕 主体（sub）

Payload 方法

Guard 接口

Storage 接口

事件类

TokenIssued

TokenExpired

TokenRevoked

异常类

📚 最佳实践

1. 密钥管理

2. 多守卫配置

3. 事件监听

4. 错误处理

🔧 扩展指南

自定义存储驱动

注册自定义驱动：

自定义守卫

📦 依赖与兼容性

必需依赖

可选依赖

兼容环境

All versions of jwt with dependencies

PHP Build Version
Package Version
Requires php Version ^8.3
ext-json Version *
ext-openssl Version *
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package kode/jwt contains the following files

Loading the files please wait ...