Download the PHP package lzpeng/gaara-hyperf-jwt without Composer

Gaara Hyperf JWT

English

Gaara Hyperf JWT 是一个面向 API 场景的 JWT 认证扩展，用于在 Gaara Hyperf 中快速接入 Access Token 与 Refresh Token 机制。它内置 JWT 认证器、登录成功处理器、刷新令牌管理与可自定义响应能力，适合需要无状态认证、短期访问令牌和安全刷新流程的项目使用。

安装

快速开始

配置示例：

默认流程：

1. 登录成功后由 JWTSuccessHandler 调用对应的 JWT Manager 签发 Token。
2. 后续请求通过 Authorization: Bearer <token> 携带 Access Token。
3. Access Token 过期后，请求配置的 refresh_token_path 获取新 Token。

默认 body 响应示例：

核心配置

authenticators.jwt

• jwt_manager 用于关联 services.jwt_managers 中的具体配置。
• Access Token 提取、Refresh Token 提取、刷新路径与响应格式，统一在对应的 JWT Manager 配置中定义。

JWTSuccessHandler

• success_handler 与 authenticators.jwt 建议使用同一个 jwt_manager。
• 登录成功后，JWTSuccessHandler 会自动签发 Access Token，并在启用时同时签发 Refresh Token。
• 如果用户实现了 JWTCustomClaimAwareUserInterface，其自定义 Claims 会一并写入 Access Token。

services.jwt_managers

高级能力

自定义 Claims

用户对象实现 GaaraHyperf\JWT\JWTCustomClaimAwareUserInterface 后，getJWTCustomClaims() 的返回值会注入到 Access Token：

自定义 Responder

如果你需要完全自定义登录成功后的响应结构，可以为 token_responder 指定自定义实现：

• 自定义响应器必须实现 GaaraHyperf\JWT\JWTokenManager\JWTokenResponder\JWTokenResponderInterface。
• 如果只需要改返回 JSON 结构，优先使用 template 即可，无需自定义类。

刷新与登出

• 刷新请求命中 refresh_token_path 时，旧 Refresh Token 会被撤销，再签发新 Token。
• 开启 Refresh Token 后，会自动注册登出监听器。
• 登出撤销仅在 POST 请求中生效。

JWTRevokeLogoutListener 使用说明

JWTRevokeLogoutListener 会在启用 JWT 认证器后自动注册，无需手动绑定。它会监听登出事件，并在满足条件时撤销当前请求携带的 Refresh Token。

要触发 LogoutEvent，除了启用 JWT 认证外，还需要配置 logout_path。只有当请求命中该路径时，Gaara Hyperf 才会将其识别为登出请求并派发登出事件。

生效条件如下：

• 已启用 Refresh Token 机制；
• 已配置 logout_path；
• 当前请求路径命中 logout_path；
• 请求方法为 POST；
• 请求中能够被 refresh_token_extractor 正常提取到 Refresh Token。

典型场景是用户调用登出接口时，服务端同步废弃当前 Refresh Token，避免退出后旧 Token 继续用于刷新。

如果你使用的是请求体提取方式，确保登出请求中也携带对应的 refresh_token 字段；如果使用 Cookie 提取方式，则需要保证请求会附带相应 Cookie。

常见问题

缺少 refresh_token_path

开启 Refresh Token 后，必须在对应的 jwt_manager 配置中设置 refresh_token_path。

Token 无效或未携带

• 检查 Authorization: Bearer <token> 是否正确。
• 如果使用 Cookie 模式，记得把 refresh_token_extractor 改成 cookie。
• 检查 jwt_manager、secret_key、iss、aud 与签发时是否一致。

Refresh Token 无效

常见原因：已过期、已被刷新撤销、或 single_session 导致旧 Token 失效。

自定义模板不是合法 JSON

template 必须是合法 JSON 字符串。