Search by

fiberphp / snowflake

fiberphp

❄️ FiberPHP 雪花算法 ID 生成器 —— 64 位分布式唯一 ID,支持 Redis 租约自动分配 workerId、时钟回拨保护,零依赖。

v0.1.0 2026-11-22 08:51 UTC

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();

配置

键默认值说明
epoch1704067200000自定义纪元(毫秒时间戳),ID 时间位存当前时间与纪元之差
clock_back_tolerance5时钟回拨容忍毫秒数,阈值内等待追平,超阈值抛异常
worker_ttl30Redis 租约 TTL(秒),心跳按此值续期
worker_idnull手动指定节点号;为 null 时必须注入 Redis 自动分配

行为说明

  • 同一毫秒内最多生成 4096 个 ID,用尽后自动等待下一毫秒。
  • 时钟回拨在 clock_back_tolerance 容忍范围内等待追平,超出范围抛出异常。
  • Redis 租约到期前自动续期;进程退出时可调用 releaseWorkerId() 提前释放。

License

MIT License (c) 2026 FiberPHP Contributors,详见 LICENSE。