PHPackages                             kylesean/hyperf-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. kylesean/hyperf-jwt

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

kylesean/hyperf-jwt
===================

A JWT (JSON Web Token) package for Hyperf framework.

v1.2.0(4mo ago)08MITPHPPHP >=8.1

Since May 25Pushed 4mo agoCompare

[ Source](https://github.com/kylesean/hyperf-jwt)[ Packagist](https://packagist.org/packages/kylesean/hyperf-jwt)[ RSS](/packages/kylesean-hyperf-jwt/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (17)Versions (4)Used By (0)

Hyperf JWT
==========

[](#hyperf-jwt)

[![Latest Stable Version](https://camo.githubusercontent.com/14b9e2b8fcd80e7be441d5dd20de9b2362571bf28969035e8fe004bbb73116fe/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b796c657365616e2f6879706572662d6a77742e737667)](https://packagist.org/packages/kylesean/hyperf-jwt)[![License](https://camo.githubusercontent.com/a7d0510271ffcfc9477e6e2cbac566eeadc63a9301b468384d7cc538c7dd8616/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6b796c657365616e2f6879706572662d6a77742e737667)](https://packagist.org/packages/kylesean/hyperf-jwt)

为 [Hyperf](https://hyperf.io/) 框架量身定制的 JWT (JSON Web Token) 专业认证扩展包。基于强大的 `lcobucci/jwt` v5.4+ 构建，提供高性能、强类型且符合 PSR 标准的认证方案。

✨ 特性
----

[](#-特性)

- **库版本对齐**：全面支持 `lcobucci/jwt` v5.4+ 的不可变 API。
- **架构解耦**：基于工厂模式和依赖注入，核心 `Manager` 高度解耦。
- **中间件支持**：内置标准的身份验证中间件。
- **异常桥接**：将复杂的验证失败精准转化为业务语义异常（过期、非法、尚未生效）。
- **多源解析**：支持从 Header、Query、Cookie 等多种途径提取令牌。
- **黑名单机制**：支持 Token 主动注销与刷新。

📦 安装
----

[](#-安装)

```
composer require kylesean/hyperf-jwt
```

🛠️ 配置
-----

[](#️-配置)

### 1. 发布配置文件

[](#1-发布配置文件)

```
php bin/hyperf.php vendor:publish kylesean/hyperf-jwt
```

### 2. 生成密钥 (ECC 或 HMAC)

[](#2-生成密钥-ecc-或-hmac)

```
# 生成 HS256 密钥
php bin/hyperf.php jwt:gen-key --algo=HS256
```

请参考 `config/autoload/jwt.php` 完善 `issuer`, `audience`, `ttl` 等核心配置。

🚀 快速开始
------

[](#-快速开始)

### 签发 Token

[](#签发-token)

```
use Kylesean\Jwt\Contract\ManagerInterface;

public function login(ManagerInterface $manager)
{
    $customClaims = ['role' => 'admin'];
    $userId = 1;

    // 签发 Token (返回 TokenInterface 对象)
    $token = $manager->issueToken($customClaims, $userId);

    return [
        'access_token' => $token->toString(),
    ];
}
```

### 身份验证中间件

[](#身份验证中间件)

在路由或控制器上挂载 `Kylesean\Jwt\Middleware\JwtAuthMiddleware` 即可实现自动拦截。

```
// config/routes.php
Router::addGroup('/admin', function () {
    Router::get('/profile', [App\Controller\UserController::class, 'profile']);
}, ['middleware' => [Kylesean\Jwt\Middleware\JwtAuthMiddleware::class]]);
```

🛡️ 异常处理
-------

[](#️-异常处理)

本插件会将验证失败的具体原因桥接到以下异常，建议在 `App\Exception\Handler` 中统一捕获：

异常类含义建议响应`TokenExpiredException`令牌已过期HTTP 401 (Code: 40101)`TokenInvalidException`签名错误或被黑名单HTTP 401 (Code: 40102)`TokenNotYetValidException`令牌尚未到生效时间HTTP 401`JwtException`其他 JWT 内部错误HTTP 500⚙️ 高级用法
-------

[](#️-高级用法)

### 自定义载荷工厂 (PayloadFactory)

[](#自定义载荷工厂-payloadfactory)

若需精细控制签发逻辑，可替换默认工厂：

```
// config/dependencies.php
return [
    \Kylesean\Jwt\Contract\PayloadFactoryInterface::class => \App\Jwt\CustomPayloadFactory::class,
];
```

⚖️ 许可证
------

[](#️-许可证)

MIT License.

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance75

Regular maintenance activity

Popularity4

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 90.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~111 days

Total

3

Last Release

136d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c37bf830f544efc8c93ba5220fe9b7344efd02e54cfaae3bebd964d27da1971d?d=identicon)[kylesean](/maintainers/kylesean)

---

Top Contributors

[![kylesean](https://avatars.githubusercontent.com/u/19353263?v=4)](https://github.com/kylesean "kylesean (10 commits)")[![jkxsai666](https://avatars.githubusercontent.com/u/247395285?v=4)](https://github.com/jkxsai666 "jkxsai666 (1 commits)")

---

Tags

phpjwtJSON Web Tokenhyperf

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/kylesean-hyperf-jwt/health.svg)

```
[![Health](https://phpackages.com/badges/kylesean-hyperf-jwt/health.svg)](https://phpackages.com/packages/kylesean-hyperf-jwt)
```

###  Alternatives

[tymon/jwt-auth

JSON Web Token Authentication for Laravel and Lumen

11.5k49.1M350](/packages/tymon-jwt-auth)[hyperf-ext/jwt

The Hyperf JWT package.

53134.9k2](/packages/hyperf-ext-jwt)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)