Download the PHP package petalbranch/jpt without Composer

Json Petal Token (JPT)

🌏 语言/Language

• 👉 中文
• English

📘 简介

PetalBranch/jpt (Json Petal Token) 是一个轻量级、安全且灵活的 PHP 令牌生成与验证库。

不同于传统的 JWT，JPT 引入了 "Petal" (花瓣) 概念，支持部分数据加密 。它采用独特的三段式结构，既保留了公开数据的透明性，又通过加密段确保存储在客户端的敏感数据（如用户手机号、邮箱等）不被泄露。

✨ 特性

• 🔒 混合加密结构：公开区 (Crown) 使用 Base64URL，私有区 (Petal) 使用petal-cipher加密兼顾隐私。
• 🛡️ 安全签名：支持 HMAC 系列算法 (HS256 / HS384 / HS512)，防止数据篡改。
• 🧩 灵活配置：轻松设置签发人 (iss)、受众 (aud)、过期时间 (exp) 及 生效时间 (nbf)。
• ⏱ 容错机制：支持时间漂移容差 (leeway)，适应分布式系统的时间偏差。
• 📦 强类型载荷：验证后返回强类型 JptPayload 对象，开发体验更佳。
• ⚡ 便捷路径访问：(v1.3.0+) 支持类似 CSS 选择器的点号语法 ($payload('c.user.name')) 快速读取深层嵌套数据。

📦 安装

推荐使用 Composer 进行安装：

🚀 快速开始

1. 生成 Token 并获取元数据

2. 验证 Token

⚙️ 配置选项

初始化 Jpt 类时支持以下配置参数：

📚 令牌结构

结构示例：

🌟 JptPayload 捷径访问 (v1.3.0+)

Jpt 类提供了一种捷径访问方式，用于读取嵌套数据。

基本语法

• 根节点简写：
  • c 或 crown：访问公开数据区 (Crown)
  • p 或 petal：访问私密数据区 (Petal)
• 自动分割：使用 . 自动层层深入数组。
• 安全空值：如果路径不存在，返回 null (不会报错)，方便使用 ?? 设置默认值。

场景对比

高级用法：多参数模式

如果您的键名中本身包含点号 (.)，或者需要动态拼接路径，可以传入多个参数：

📖 API 参考手册

1. Jpt 类 (核心操作)

基础配置 (Chainable)

支持链式调用，用于动态修改初始化时的配置。

• setOption(string $key, mixed $value): self - 设置通用配置项。
• setOptIss(string $iss): self - 设置签发人。
• setOptAud(string $aud): self - 设置受众。
• setOptTtl(int $ttl): self - 设置生命周期(秒)。
• setOptLeeway(int $leeway): self - 设置时间漂移容差。
• setOptNbf(?int $nbf): self - 设置生效时间 (传入 null 可移除)。

数据装载 (Chainable)

用于设置 Token 内携带的业务数据。

• setCrownData(array $data): self - 批量设置公开数据 (Crown)。
• withCrown(string $key, mixed $value): self - 添加单项公开数据。
• setPetalData(array $data): self - 批量设置私密数据 (Petal)。
• withPetal(string $key, mixed $value): self - 添加单项私密数据。
• withoutCrown(string $key): self - 移除某项公开数据。
• withoutPetal(string $key): self - 移除某项私密数据。

核心动作

• generate(): string - 生成最终的 Token 字符串。
• toJptPayload(): JptPayload - 获取当前数据的载荷对象 (包含生成的 jti, exp 等)。常用于生成后立即获取元数据。
• validate(string $token): JptPayload - 验证并解析 Token 字符串。

2. JptPayload 类 (结果对象)

validate() 和 toJptPayload() 的返回结果，所有属性均为 Readonly。

公开属性

可以直接访问以下属性：

• $payload->iss (string) - 签发人
• $payload->sub (?string) - 主题
• $payload->aud (string) - 受众
• $payload->jti (string) - 唯一标识 ID
• $payload->exp (int) - 过期时间戳
• $payload->iat (int) - 签发时间戳
• $payload->nbf (int) - 生效时间戳
• $payload->raw (string) - 原始 Token 字符串 (v1.3.0+)。

⚠️ 重要提示 (破坏性变更): 旧属性 $payload->payload 已在 v1.3.0 中被彻底移除。

• 该属性仅在 v1.2.x 版本中可用。
• 在 v1.3.0 及更高版本中，访问 $payload->payload 将导致错误。
• 请务必使用 $payload->raw 替代。

辅助方法

• getCrownData(?string $key, mixed $default): mixed - 获取 Crown 数据。不传 key 返回整个数组。
• getPetalData(?string $key, mixed $default): mixed - 获取 Petal 数据 (已解密)。不传 key 返回整个数组。
• getExpiration(): int - 获取距离过期的剩余秒数 (已过期返回 0)。

📜 更新日志

[1.3.2] - 2026-03-14

Changed

• [Docs] 更新 README.md 中的稳定版本号为 v1.3.2。
• [Refactor] 破坏性变更说明：明确文档指出 $payload->payload 属性已在 v1.3.0 中被移除。该属性仅在 v1.2.x 版本中可用，新版本必须使用 $payload->raw 获取原始 Token 字符串。
• [Docs] 完善 API 属性列表说明，添加醒目的迁移警告，指导用户从旧版属性切换到 raw。

Fixed

• [Docs] 修复英文文档 (README_EN.md) 中的段落格式及表格对齐问题。
• [Docs] 全面检查并修正文档中的代码示例，确保所有示例均使用 $payload->raw，避免误导用户。

⚠️ 重要迁移提示 (Breaking Change): 属性 $payload->payload 已于 v1.3.0 正式移除。

• ❌ 错误用法 (v1.3.0+): $token = $payload->payload; (将抛出异常)
• ✅ 正确用法: $token = $payload->raw;

请确保您的代码已更新至使用 raw 属性。

👀 历史更新

📄 许可证

本项目遵循 Apache License 2.0 开源协议。