fiberphp / snowflake
❄️ FiberPHP 雪花算法 ID 生成器 —— 64 位分布式唯一 ID,支持 Redis 租约自动分配 workerId、时钟回拨保护,零依赖。
v0.1.0
2026-11-22 08:51 UTC
Requires
- php: >=8.5
Requires (Dev)
- phpstan/phpstan: ^2.0
- phpunit/phpunit: ^11.0
Suggests
- ext-redis: 使用 Redis 租约自动分配 workerId 时需要
- workerman/workerman: 协程环境下用 Timer::sleep 让出事件循环,避免阻塞其他协程
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-22 08:53:38 UTC
README
❄️ 雪花算法分布式唯一 ID 生成器 —— 64 位、趋势递增、零依赖。
环境要求
- PHP >= 8.5
- 多实例自动分配 workerId 时需要
ext-redis - 协程环境建议安装
workerman/workerman(通过Timer::sleep让出事件循环)
安装
composer require fiberphp/snowflake
快速开始
use FiberPHP\Snowflake\Snowflake;
// 手动指定 workerId(0~1023),适合容器编排已分配固定节点号的场景
$snowflake = new Snowflake(['worker_id' => 1]);
$id = $snowflake->nextId();
$ids = $snowflake->nextIds(100);
$timestamp = $snowflake->parseTimestamp($id); // 毫秒时间戳
$workerId = $snowflake->parseWorkerId($id); // 节点号
多实例部署且无固定节点号时,传入 Redis(需安装 ext-redis),由 Redis 租约自动分配 workerId:
$redis = new Redis();
$redis->connect('127.0.0.1', 6379);
$snowflake = new Snowflake([], $redis);
$id = $snowflake->nextId();
// 进程退出前释放租约(失败也无妨,TTL 到期自动清理)
$snowflake->releaseWorkerId();
配置
| 键 | 默认值 | 说明 |
|---|---|---|
epoch | 1704067200000 | 自定义纪元(毫秒时间戳),ID 时间位存当前时间与纪元之差 |
clock_back_tolerance | 5 | 时钟回拨容忍毫秒数,阈值内等待追平,超阈值抛异常 |
worker_ttl | 30 | Redis 租约 TTL(秒),心跳按此值续期 |
worker_id | null | 手动指定节点号;为 null 时必须注入 Redis 自动分配 |
行为说明
- 同一毫秒内最多生成 4096 个 ID,用尽后自动等待下一毫秒。
- 时钟回拨在
clock_back_tolerance容忍范围内等待追平,超出范围抛出异常。 - Redis 租约到期前自动续期;进程退出时可调用
releaseWorkerId()提前释放。
License
MIT License (c) 2026 FiberPHP Contributors,详见 LICENSE。