PHPackages                             kode/jwt - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. kode/jwt

ActiveLibrary[Authentication & Authorization](/categories/authentication)

kode/jwt
========

为现代 PHP 应用提供安全、灵活、高性能的 JWT 身份验证解决方案，支持单点登录（SSO）、多点登录、黑名单管理、自动续期、多平台适配，兼容 FPM、Swoole、RoadRunner 等运行环境。

1.8.2(1w ago)11331Apache-2.0PHPPHP ^8.2

Since Sep 20Pushed 1mo agoCompare

[ Source](https://github.com/kodephp/jwt)[ Packagist](https://packagist.org/packages/kode/jwt)[ RSS](/packages/kode-jwt/feed)WikiDiscussions master Synced today

READMEChangelogDependencies (10)Versions (18)Used By (0)

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

[](#kode-jwt一个健壮全面现代化的-php-82-jwt-包)

> **项目名称**：`kode/jwt`
> **当前版本**：`v1.8.2`
> **目标**：为现代 PHP 应用提供安全、灵活、高性能的 JWT 身份验证解决方案，支持单点登录（SSO）、多点登录、黑名单管理、自动续期、多平台适配、防重放攻击（Anti-Replay），兼容 FPM、Swoole、RoadRunner 等运行环境。

---

📌 项目愿景
------

[](#-项目愿景)

构建一个**生产级、零侵入、高可扩展**的 JWT 包，专为 PHP 8.1+ 设计，充分利用现代 PHP 特性（如属性、联合类型、泛型模拟、反射优化），并支持主流框架（Laravel、Symfony、ThinkPHP、Hyperf、EasySwoole 等）无缝接入。 可使用kode相关包或其他通用适合的包快速集成。

---

🚀 核心特性
------

[](#-核心特性)

特性说明✅ **PHP 8.2+ 原生支持**使用 `readonly` 类、`readonly` 属性、`enum`、`never`、`true/false` 类型、`intersection types`（模拟）等新特性✅ **多平台支持**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 列表"三步原子性---

📁 项目结构（PSR-4）
-------------

[](#-项目结构psr-4)

```
src/
├── Contract/           # 所有接口定义
│   ├── TokenManagerInterface.php
│   ├── StorageInterface.php
│   ├── GuardInterface.php
│   └── EventInterface.php
├── Token/              # Token 核心类
│   ├── Builder.php
│   ├── Parser.php
│   ├── Claim.php
│   └── Payload.php
├── Guard/              # 守卫机制
│   ├── BaseGuard.php
│   ├── SsoGuard.php
│   └── MloGuard.php
├── Storage/            # 存储驱动
│   ├── RedisStorage.php
│   ├── MemoryStorage.php
│   └── NullStorage.php
├── Exception/          # 自定义异常
│   ├── TokenInvalidException.php
│   ├── TokenExpiredException.php
│   └── TokenBlacklistedException.php
├── Event/              # 事件系统
│   ├── TokenIssued.php
│   └── TokenRevoked.php
├── Config/             # 配置管理
│   └── ConfigLoader.php
└── KodeJwt.php         # 主门面/工厂类
```

---

🛠️ 安装方式
-------

[](#️-安装方式)

```
composer require kode/jwt
```

### CLI 工具初始化

[](#cli-工具初始化)

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

```
# 进入你的项目目录
cd /path/to/your/project

# 安装配置文件和生成密钥（RSA 密钥对 + HMAC 密钥）
php vendor/bin/jwt install

# 或者仅生成配置文件
php vendor/bin/jwt install --config-only

# 或者仅生成密钥
php vendor/bin/jwt install --key-only

# 强制覆盖已存在的文件
php vendor/bin/jwt install --force
```

### 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 命令选项

[](#install-命令选项)

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

[](#key-命令选项)

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

```
# 生成 RSA 密钥对（默认）
php jwt key rsa

# 生成 HMAC 密钥
php jwt key hmac

# 生成并输出到控制台
php jwt key rsa stdout

# 强制覆盖现有密钥
php jwt key rsa --force
```

### 生成的文件结构

[](#生成的文件结构)

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

```
your-project/
├── config/
│   └── jwt.php          # JWT 配置文件
└── storage/
    └── keys/
        ├── secret       # HMAC 密钥（用于 HS256）
        ├── private.pem  # RSA 私钥（用于 RS256 签名）
        └── public.pem   # RSA 公钥（用于 RS256 验证）

```

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

---

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

[](#-配置文件configjwtphp)

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

```