PHPackages                             vinchan/token - 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. vinchan/token

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

vinchan/token
=============

A simple and powerful JWT library for Hyperf framework

00PHPCI failing

Since Jun 7Pushed 11mo agoCompare

[ Source](https://github.com/VinchanGit/token)[ Packagist](https://packagist.org/packages/vinchan/token)[ RSS](/packages/vinchan-token/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

JWT Token Library (vinchan/token)
=================================

[](#jwt-token-library-vinchantoken)

一个简洁而强大的PHP JWT库，专为现代PHP应用设计。

特性
--

[](#特性)

- 🚀 **极简设计** - 只有2个核心类，API简洁直观
- 🛡️ **类型安全** - 完整的PHP 8.2+ 类型声明
- 🔐 **多算法支持** - 支持HMAC、RSA、ECDSA算法族
- ⚙️ **配置驱动** - 支持多环境配置，灵活切换
- 🎯 **零依赖** - 除PHP标准库和OpenSSL外无额外依赖
- ✅ **全面测试** - 单元测试覆盖率高，质量可靠

安装
--

[](#安装)

```
composer require vinchan/token
```

快速开始
----

[](#快速开始)

### 基础用法

[](#基础用法)

```
use Vinchan\Token\Authenticatable;
use Vinchan\Token\TokenManager;

// 创建用户信息
$user = new Authenticatable('user123', [
    'name' => 'John Doe',
    'role' => 'admin',
    'email' => 'john@example.com'
]);

// 生成token
$token = TokenManager::create()
    ->payload($user)
    ->ttl(3600)        // 1小时过期
    ->generate('your-secret-key');

// 验证token
$isValid = TokenManager::create()->verify($token, 'your-secret-key');

// 获取用户信息
$userInfo = TokenManager::create()->info($token, 'your-secret-key');
if ($userInfo) {
    echo $userInfo->getId();        // user123
    echo $userInfo->get('name');    // John Doe
    echo $userInfo->get('role');    // admin
}
```

### 配置文件方式

[](#配置文件方式)

创建配置文件 `config/autoload/token.php`：

```
return [
    'default' => [
        'algorithm' => 'HS256',
        'secret_key' => env('JWT_SECRET', 'your-secret-key'),
        'ttl' => 3600,
        'issuer' => 'your-app',
        'audience' => 'api',
    ],
    'admin' => [
        'algorithm' => 'HS512',
        'secret_key' => env('JWT_ADMIN_SECRET', 'admin-secret'),
        'ttl' => 7200,
        'issuer' => 'admin-panel',
    ],
];
```

使用配置：

```
// 使用默认配置
$token = TokenManager::create()
    ->payload($user)
    ->generate(); // 自动从配置获取密钥

// 使用指定配置
$adminToken = TokenManager::with('admin')
    ->payload($user)
    ->generate();

// 验证时也会自动使用配置
$isValid = TokenManager::create()->verify($token);
$userInfo = TokenManager::create()->info($token);
```

核心类
---

[](#核心类)

### TokenManager

[](#tokenmanager)

主要的JWT处理类，提供流畅的API：

```
$manager = TokenManager::create()
    ->payload($authenticatable)    // 设置载荷
    ->algorithm('HS256')          // 设置算法
    ->ttl(3600)                   // 设置过期时间
    ->issuer('my-app')            // 设置签发者
    ->audience('api')             // 设置受众
    ->config('admin')             // 指定配置键
    ->generate($secretKey);       // 生成token
```

**主要方法：**

- `generate(?string $key = null): string` - 生成JWT token
- `verify(string $token, ?string $key = null): bool` - 验证token有效性
- `info(string $token, ?string $key = null): ?Authenticatable` - 获取token信息

**静态工厂方法：**

- `TokenManager::create()` - 创建实例
- `TokenManager::with(string $configKey)` - 使用指定配置创建实例

### Authenticatable

[](#authenticatable)

用户身份信息值对象：

```
// 创建用户信息（ID必须）
$user = new Authenticatable('user123', [
    'name' => 'John',
    'role' => 'admin',
    'permissions' => ['read', 'write']
]);

// 访问数据
$user->getId();                    // user123
$user->get('name');               // John
$user->get('role', 'guest');      // admin (带默认值)
$user->getData();                 // 获取所有额外数据
$user->toArray();                 // 转为数组

// 从数组创建
$user = Authenticatable::fromArray([
    'id' => 'user123',
    'name' => 'John',
    'role' => 'admin'
]);
```

支持的算法
-----

[](#支持的算法)

### HMAC算法族

[](#hmac算法族)

```
TokenManager::create()->algorithm('HS256')->payload($user)->generate('secret');
TokenManager::create()->algorithm('HS384')->payload($user)->generate('secret');
TokenManager::create()->algorithm('HS512')->payload($user)->generate('secret');
```

### RSA算法族

[](#rsa算法族)

```
// 生成时使用私钥
$token = TokenManager::create()
    ->algorithm('RS256')
    ->payload($user)
    ->generate($privateKey);

// 验证时使用公钥
$isValid = TokenManager::create()
    ->algorithm('RS256')
    ->verify($token, $publicKey);
```

### ECDSA算法族

[](#ecdsa算法族)

```
TokenManager::create()->algorithm('ES256')->payload($user)->generate($privateKey);
TokenManager::create()->algorithm('ES384')->payload($user)->generate($privateKey);
TokenManager::create()->algorithm('ES512')->payload($user)->generate($privateKey);
```

高级用法
----

[](#高级用法)

### 自定义Claims

[](#自定义claims)

```
$user = new Authenticatable('user123', [
    'name' => 'John',
    'role' => 'admin',
    'department' => 'IT',
    'permissions' => ['read', 'write', 'delete']
]);

$token = TokenManager::create()
    ->payload($user)
    ->issuer('my-company')
    ->audience('internal-api')
    ->ttl(7200)
    ->generate($key);
```

### 错误处理

[](#错误处理)

```
try {
    $token = TokenManager::create()
        ->payload($user)
        ->generate($key);

    $userInfo = TokenManager::create()->info($token, $key);

} catch (\Vinchan\Token\Exception\SignatureException $e) {
    // 签名相关错误
} catch (\Vinchan\Token\Exception\ExpiredException $e) {
    // token过期
} catch (\Vinchan\Token\Exception\InvalidTokenException $e) {
    // token格式无效
}
```

### 多环境配置

[](#多环境配置)

```
// 开发环境
$devToken = TokenManager::with('dev')
    ->payload($user)
    ->generate();

// 生产环境
$prodToken = TokenManager::with('production')
    ->payload($user)
    ->generate();

// 管理员环境
$adminToken = TokenManager::with('admin')
    ->payload($user)
    ->generate();
```

在Hyperf中使用
----------

[](#在hyperf中使用)

### 1. 发布配置文件

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

```
php bin/hyperf.php vendor:publish vinchan/token
```

### 2. 配置环境变量

[](#2-配置环境变量)

```
JWT_SECRET=your-super-secret-key-here
JWT_TTL=3600
JWT_ALGORITHM=HS256
```

### 3. 在控制器中使用

[](#3-在控制器中使用)

```