weaix/jwt

PHP框架JWT工具，基于firebase/php-jwt开发，支持Laravel/ThinkPHP/Webman

dev-main 2025-08-17 13:26 UTC

Requires

• php: >=8.0
• firebase/php-jwt: ^6.0
• symfony/filesystem: ^5.4|^6.0

MIT

• Weaix

README

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

目录

• 1. 简介
• 2. 安装
• 3. 配置
• 4. 基本使用
• 5. 框架集成
• 6. 异常处理
• 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
/**
 * +----------------------------------------------------------------------
 * | Project Name: Weaix JWT
 * | Author      : Weaix <[e-mail]>
 * | 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 生成令牌

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 验证令牌

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 提取请求头中的令牌

// 获取请求头（框架特定方法）
$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中添加：

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

5.1.3 使用中间件

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

5.1.4 使用门面

use Weaix\Jwt\Facades\Jwt;

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

5.2 ThinkPHP

5.2.1 注册中间件

在config/middleware.php中添加：

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

5.2.2 使用中间件

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中添加：

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

5.3.2 使用载荷

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异常

异常处理示例：

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 许可证开源。

8. 联系信息

• 作者：Weaix
• 邮箱：[e-mail]
• 主页：https://gitee.com/Weaix