# weaix-jwt

**Repository Path**: weaix/weaix-jwt

## Basic Information

- **Project Name**: weaix-jwt
- **Description**: PHP框架JWT认证组件，基于firebase/php-jwt开发，支持Laravel/ThinkPHP/Webman
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-08-17
- **Last Updated**: 2025-12-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Weaix JWT 工具

轻量级JWT解决方案，支持多框架集成，基于firebase/php-jwt开发

## 目录
- [1. 简介](#1-简介)
- [2. 安装](#2-安装)
- [3. 配置](#3-配置)
- [4. 基本使用](#4-基本使用)
- [5. 框架集成](#5-框架集成)
- [6. 异常处理](#6-异常处理)
- [7. 许可证](#7-许可证)

## 1. 简介

Weaix JWT 是一个功能完善的JWT工具，主要特点：

- 支持 Laravel、ThinkPHP、Webman 等主流PHP框架
- 提供令牌生成、验证、解析全套功能
- 完善的异常处理机制，错误码标准化
- 自动生成配置文件，简化集成流程
- 兼容多框架环境变量读取方式

## 2. 安装

### 2.1 环境要求
- PHP >= 8.0
- Composer

### 2.2 安装命令

```
composer require weaix/jwt
```

> 安装后会自动在项目`config`目录生成`weaix-jwt.php`配置文件

## 3. 配置

### 3.1 配置文件路径

```
config/weaix-jwt.php
```

### 3.2 配置内容

```php
<?php
/**
 * +----------------------------------------------------------------------
 * | Project Name: Weaix JWT
 * | Author      : Weaix <357356354@qq.com>
 * | Copyright   : © 2025 Weaix All rights reserved.
 * | Created     : 2025-08-17
 * | Description : JWT配置文件
 * +----------------------------------------------------------------------
 */

// Webman环境适配
if (!function_exists('env') && function_exists('config')) {
    function env(string $key, $default = null) {
        $value = config("env.{$key}", null);
        return $value !== null ? $value : (getenv($key) ?: $default);
    }
}

return [
    // 密钥，生产环境必须使用32位以上随机字符串
    'secret' => env('JWT_SECRET', 'your-secure-secret-key'),
    
    // 加密算法
    'algorithm' => env('JWT_ALGORITHM', 'HS256'),
    
    // 令牌过期时间（秒）
    'expires_at' => (int)env('JWT_EXPIRES_AT', 3600),
    
    // 令牌生效延迟时间（秒）
    'not_before' => (int)env('JWT_NOT_BEFORE', 0),
    
    // 签发者
    'issuer' => env('JWT_ISSUER', null),
    
    // 受众
    'audience' => env('JWT_AUDIENCE', null),
    
    // 主题
    'subject' => env('JWT_SUBJECT', null),
    
    // 令牌所在的请求头名称
    'header_name' => env('JWT_HEADER_NAME', 'Authorization'),
    
    // 令牌前缀
    'token_prefix' => env('JWT_TOKEN_PREFIX', 'Bearer')
];
```

### 3.3 配置参数说明

| 参数名 | 描述 | 类型 | 默认值 |
|--------|------|------|--------|
| secret | 加密密钥，生产环境必须更换 | string | your-secure-secret-key |
| algorithm | 加密算法 | string | HS256 |
| expires_at | 过期时间（秒） | int | 3600 |
| not_before | 生效延迟时间（秒） | int | 0 |
| issuer | 签发者标识 | string\|null | null |
| audience | 受众标识 | string\|null | null |
| subject | 主题标识 | string\|null | null |
| header_name | 令牌请求头名称 | string | Authorization |
| token_prefix | 令牌前缀 | string | Bearer |

## 4. 基本使用

### 4.1 生成令牌

```php
use Weaix\Jwt\Jwt;

// 初始化组件
$jwt = new Jwt(config('weaix-jwt'));

// 生成令牌（自定义载荷）
$token = $jwt->generateToken([
    'user_id' => 1001,
    'username' => 'example'
]);

// 生成指定过期时间的令牌（7200秒）
$token = $jwt->generateToken(
    ['user_id' => 1001], 
    7200
);
```

### 4.2 验证令牌

```php
use Weaix\Jwt\Jwt;
use Weaix\Jwt\Exceptions\JwtException;

try {
    $jwt = new Jwt(config('weaix-jwt'));
    $payload = $jwt->verifyToken($token);
    
    // 使用载荷数据
    echo $payload->user_id; // 1001
    echo $payload->username; // example
} catch (JwtException $e) {
    // 处理异常
    echo "错误：{$e->getMessage()}（{$e->getCode()}）";
}
```

### 4.3 提取请求头中的令牌

```php
// 获取请求头（框架特定方法）
$headers = getallheaders();

// 提取令牌
$token = $jwt->extractTokenFromHeaders($headers);
```

## 5. 框架集成

### 5.1 Laravel

#### 5.1.1 发布配置

```
php artisan vendor:publish --provider="Weaix\Jwt\Providers\LaravelServiceProvider" --tag="weaix-jwt-config"
```

#### 5.1.2 注册中间件

在`app/Http/Kernel.php`中添加：

```php
protected $routeMiddleware = [
    // 其他中间件...
    'jwt' => \Weaix\Jwt\Middleware\Laravel\JwtMiddleware::class,
];
```

#### 5.1.3 使用中间件

```php
Route::group(['middleware' => 'jwt'], function () {
    Route::get('/api/user', function (Request $request) {
        // 获取载荷
        $payload = $request->getAttribute('jwt_payload');
        return response()->json($payload);
    });
});
```

#### 5.1.4 使用门面

```php
use Weaix\Jwt\Facades\Jwt;

// 生成令牌
$token = Jwt::generateToken(['user_id' => 1001]);
```

### 5.2 ThinkPHP

#### 5.2.1 注册中间件

在`config/middleware.php`中添加：

```php
return [
    'jwt' => \Weaix\Jwt\Middleware\ThinkPHP\JwtMiddleware::class,
];
```

#### 5.2.2 使用中间件

```php
Route::group(['middleware' => 'jwt'], function () {
    Route::get('/api/user', function () {
        $payload = request()->jwt_payload;
        return json($payload);
    });
});
```

### 5.3 Webman

#### 5.3.1 配置中间件

在`config/middleware.php`中添加：

```php
return [
    'api' => [
        \Weaix\Jwt\Middleware\Webman\JwtMiddleware::class,
    ],
];
```

#### 5.3.2 使用载荷

```php
namespace app\controller;

use support\Request;

class UserController
{
    public function info(Request $request)
    {
        $payload = $request->getAttribute('jwt_payload');
        return json($payload);
    }
}
```

## 6. 异常处理

| 异常类 | 错误码 | 描述 |
|--------|--------|------|
| `ConfigurationException` | 1001 | 配置无效 |
| `InvalidTokenException` | 1002 | 令牌格式无效 |
| `SignatureInvalidException` | 1003 | 签名无效 |
| `TokenExpiredException` | 1004 | 令牌已过期 |
| `TokenMissingException` | 1005 | 令牌不存在 |
| `TokenNotBeforeException` | 1006 | 令牌未生效 |
| `JwtException` | 1000 | 其他JWT异常 |

**异常处理示例**：

```php
use Weaix\Jwt\Exceptions\{TokenExpiredException, TokenMissingException};

try {
    // JWT操作
} catch (TokenExpiredException $e) {
    return response()->json([
        'code' => $e->getCode(),
        'message' => $e->getMessage(),
        'need_refresh' => true
    ]);
} catch (TokenMissingException $e) {
    return response()->json($e->toArray(), 401);
}
```

## 7. 许可证

本组件基于 [MIT](https://opensource.org/licenses/MIT) 许可证开源。

## 8. 联系信息

- 作者：Weaix
- 邮箱：357356354@qq.com
- 主页：[https://gitee.com/Weaix](https://gitee.com/weaix)