Download the PHP package vanni/idmix without Composer

idmix — IDX v1.2 自描述序列 + 文本混淆

English: README_en.md

将多个带类型的整数或短字符串（≤63 字节）编码为短字符串，适用于 access_key、短 ID、令牌等场景。C、C++、C#、Go、Java、JavaScript、PHP、Python、Rust 多语言实现互通，遵循 IDX v1.2 规范。

如果这个项目对你有帮助，欢迎在 GitHub 上点个 ⭐ Star 支持一下：github.com/Vanni-Fan/idmix

各语言文档

两层可独立使用：

文本层通过 Codec 接口可插拔：默认 RadixCodec（自定义字符表），也可换 Base64Codec、或 FuncCodec 包装 AES/XOR 等。

也可将 Protobuf / CBOR / MessagePack 二进制直接经 EncodeBytes 输出混淆文本，替代传统的 Protobuf + AES + Base64 路径。

用途

• 类型自描述：每个整数携带原始类型（uint8 ~ uint64 / int8 ~ int64 共 8 种 otype），解码时不依赖外部 schema
• 短字符串：扩展模式支持 ≤63 字节的 UTF-8/字节串
• 极致压缩：[0, 15] 的正数、[-1, -15] 的负数仅占 1 字节；单对象时 header 仅 1 字节
• 32 态多态：同一组数据可生成最多 32 种不同编码（variant 异或混淆）
• 轻量自校验：2-bit 全局 XOR 校验，约 75% 的随机篡改可被即时拒绝
• 文本混淆（idmix 层）：默认 62 进制字符表，可单独包装任意二进制

算法概要（IDX v1.2 + idmix）

1. IDX 二进制层

二进制块 = 1 或 2 字节 header + 数据对象序列。

Header（单对象，1 字节）：

Header（多对象，2 字节）：字节 0 的 bit7=1，字节 1 为 count（2~255）。

数据对象：

• 内嵌模式（1 字节）：小整数 [-15,15]
• 扩展数字（1+ 字节）：bit6=0，有符号类型用二补码小端负载（无独立符号位）
• 扩展字符串（1+ 字节）：bit6=1，bit5-0 为长度（1~63），后跟原始字节

变体混淆：mask = (variant_id × 0x9D + 0x37) & 0xFF，对对象区逐字节 XOR（header 不参与）。

规范示例 uint16(5), int64(-1), uint32(40)（variant=0，三对象）的二进制块：

完整协议见 arithmetic.md。

2. idmix 文本层

在二进制块前附加 2 字节大端长度前缀，整体按自定义进制（默认 62 字符表）转为字符串。可单独用于任意二进制，不限于 IDX 输出。

与 Sqids 功能对比

Sqids 是流行的短 ID 库，仅支持非负整数序列。idmix 在此基础上面向结构化 access_key 场景做了扩展。

关于阻止列表：idmix 不提供 Sqids 式的 blocklist 过滤。原因是 idmix 内置 32 态变体多态，减小最大元素个数，还可以进一步增多变体数量——同一组数据每次编码会随机选取不同 variant_id，字符串形态天然分散，出现特定敏感词的概率极低；若偶发不满意，重新调用 Encode 即可得到另一变体。配合 2-bit 校验，随机猜测的有效率也更低。

以下为 Go 与 Rust 实现相对 sqids 的编码长度与性能对比（本机单线程，20000 次采样；idmix 长度含 32 态变体，报告 min~max）。极值对比中 sqids 仅支持非负整数，int64_max / uint64_max 以 uint64 传入；带负数的 int32_min / int64_min / mixed_extremes 为 idmix 独有能力（见文末）。

编码长度

sqids 在纯非负小整数场景下字符串更短；idmix 因 header、类型标记和变体开销略长，但小整数密集时反而更短（内嵌模式 1 字节/值）。极值单字段时 idmix 仍略长于 sqids（如 uint32_max：10 vs 7），但三元组极值序列差距缩小（35 vs 31）。

编码性能（idmix / sqids 倍数，>1 表示 idmix 更快）

idmix 编解码以位运算为主，显著快于 sqids；Go 实现整体快于 Rust（Rust 文本层使用 num-bigint）。 极值场景下 idmix 编码优势仍明显（7.8× - 47×），解码优势随数值增大而收窄（大整数 radix 解码约 1.3× - 2.6×，仍快于或接近 sqids）。

idmix 额外能力（sqids 不支持）

• 带类型：uint16(5), int64(-1), uint32(40) → 9 字符
• 负数与有符号极值：int32_min → 10 字符，int64_min → 16 字符
• 含负数的 mixed_extremes（五字段极值）→ 54 字符
• 随机变体：同一输入多次编码产生不同字符串

运行对比测试：

与 MessagePack / CBOR / Protobuf 对比（IDX 二进制层）

以下对比 IDX 二进制字节数与 MessagePack、CBOR、Protobuf（无 schema、逐字段带 otype+val），不含 base64 或 idmix 文本层，与 MsgPack/CBOR/Protobuf 公平对比。

编码长度（字节）

mixed_extremes 含五个极值单字段；string_example = "hello" + uint16(5) + "世界"（variant=0，Go 参考实现实测）。

IDX 在 typed 整数场景下二进制体积通常远小于 MsgPack；短字符串内联时与 CBOR 接近。

编解码性能（IDX 二进制层，相对倍数）

Go 参考实现，单线程，每项 20000 次采样。倍数为 IDX ops/s ÷ 对方 ops/s；>1 表示 IDX 更快。

编码

解码

小结：IDX 二进制编解码在中小整数场景显著快于 MsgPack/CBOR；若需 URL 可读字符串，再叠加 idmix 文本层。

运行对比测试：

各语言实现与 uint64 支持

所有实现均覆盖 uint8~uint64（及对应有符号类型 int8~int64，共 8 种 otype）；扩展模式负载为无符号小端字节，otype 标明类型，有符号类型编码时去掉冗余符号扩展字节以压缩体积。

不支持原生 uint64 时的解码表示

各语言在二进制协议层完全互通，但解码后返回给调用方的数值类型因语言而异。跨语言解码超大整数时，请按目标语言的表示方式处理：

PHP 示例（解码其它语言编码的 uint64 超大数）：

JavaScript 示例：

注意：JavaScript 用 bigint 而非字符串表示超大整数；只有 PHP（以及跨语言 JSON 向量文件）使用十进制字符串。比较时请用 typedValuesEqual() 或各语言提供的等价工具，不要直接 === 跨语言比较。

扩展模式说明

arithmetic.md 第 2.2 节核心思路：

1. 扩展数字（bit6=0）：有符号类型用二补码小端负载，无符号类型用无符号小端；不再使用 bit6 符号位。
2. 扩展字符串（bit6=1）：bit5-0 为长度（1~63），后跟原始字节。
3. 存储宽度 sw 仅由数值大小决定，与 otype 位宽无关。
4. 内嵌模式（bit7=0）：覆盖 [-15, 15]（+16 占 2 字节扩展）。
5. 单对象 header 仅 1 字节，多对象时追加 count 字节。

跨语言互操作测试

共享向量文件：[testdata/cross_language_vectors.json](testdata/cross_language_vectors.json)（由 Go 参考实现生成）。

快速开始

Go

PHP

需要 PHP 8.1+ 及 ext-bcmath、ext-mbstring 扩展（composer.json 已声明）。整数经 bcmath 以十进制字符串运算，32/64 位 PHP 均可处理完整 uint64 范围。

Rust

Python

JavaScript (Node.js)

Java

Maven 依赖（Maven Central）：

C

VB.NET

C++

C/C++ 没有类似 npm / crates.io 的统一官方包仓库，无需额外「发布」步骤。用户在自己的 CMake 工程里通过 FetchContent 从 GitHub 拉取源码即可（下面这段 CMake 是用户项目里写的，不是本仓库维护项）：

也可 clone 后本地构建：

C

同样通过 FetchContent 集成（SOURCE_SUBDIR 改为 c，链接 idmix::c）：

或本地构建：

自定义字符表

项目结构

运行测试（详细输出）

包安装（无需 git clone）

当前版本 0.4.0（IDX v1.2）。各语言可通过包管理器直接安装；发布细节见 PACKAGING.md。

C/C++ 说明：没有像 PyPI / NuGet 那样的统一官方包仓库，也不需要你再去某个官网「发布」。仓库里的 cpp/、c/ 即为源码库；用户在自己的 CMake 工程里写 FetchContent_Declare(...) 从 GitHub 拉取即可。可选的 vcpkg 端口尚未提交上游，不影响使用。

限制

• 单次编码最多 255 个对象
• 字符串单段最长 63 字节
• 推荐用于中小整数；过大数值压缩率下降
• 变体随机选取，同一输入多次 Encode 字符串不同，但均可正确解码
• PHP 依赖 ext-bcmath；未安装时运行时将抛出明确错误

许可证

Apache-2.0

觉得有用的话，欢迎给项目点个 ⭐：github.com/Vanni-Fan/idmix