fiberphp / snowflake

dev-master 2026-09-09 05:55 UTC

Requires

• php: >=8.3

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

• PangBin

• id
• snowflake
• unique-id
• distributed-id
• fiberphp

Published on Packagist.org on 2026-09-09 05:55 UTC

README

分布式唯一 ID 生成器，基于雪花算法，零框架依赖的纯库实现。10 位 workerId + 12 位序列号，单节点每毫秒可产出 4096 个 ID；未指定 workerId 时通过 Redis SETNX 租约自动分配，并随 nextId 惰性续期。

环境要求

• PHP >= 8.3
• 自动分配 workerId 时需注入 Redis 连接对象（支持 set / eval / expire，如 fiberphp/redis 的 sync 连接或原生 \Redis）

安装

composer require fiberphp-ext/snowflake

快速开始

use FiberPHP\Snowflake\Snowflake;

// 方式一：显式指定 workerId（单节点 / 自行分配时）
$snowflake = new Snowflake(['worker_id' => 1, 'epoch' => 1704067200000]);

$id = $snowflake->nextId();
// 1234567890123456789

// 批量生成
$ids = $snowflake->nextIds(1000);

Redis 自动分配 workerId

未指定 worker_id 时，构造第二参数传入 Redis 连接，自动用 SETNX + TTL 抢占空闲槽位（0~1023）：

$snowflake = new Snowflake(
    ['epoch' => 1704067200000, 'worker_ttl' => 30],
    $redis,  // Redis sync 连接对象
);

$id = $snowflake->nextId();  // 内部随每次调用惰性续期租约

// 优雅关闭时释放 workerId
$snowflake->releaseWorkerId();

配置说明

参数	默认值	说明
epoch	1704067200000	起始时间戳（毫秒），所有 ID 基于此点计算
worker_id	null	显式 workerId（0~1023）；为空则走 Redis 自动分配
worker_ttl	30	Redis 租约有效期（秒），过期未续期则槽位被回收
clock_back_tolerance	5	时钟回拨容忍阈值（毫秒），超出抛 RuntimeException

特性

能力	说明
趋势递增	时间戳高位，单节点 ID 单调递增，索引友好
Redis 租约	SETNX 抢占 workerId + Lua 原子续期，归属校验防误续他人租约
时钟回拨保护	小幅回拨等待对齐，超阈值抛异常 fail-fast
惰性心跳	每次 nextId 自动续期，无需外部定时器
解析能力	parseTimestamp / parseWorkerId 从 ID 还原元信息

License

MIT License (c) 2026 庞斌，详见 LICENSE。