# snowflake **Repository Path**: fiberphp/snowflake ## Basic Information - **Project Name**: snowflake - **Description**: ❄️ FiberPHP 雪花ID组件 —— 分布式唯一ID生成器,基于 Twitter Snowflake 算法,高性能、有序递增,协程安全,开箱即用。 - **Primary Language**: PHP - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-23 - **Last Updated**: 2026-11-22 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # fiberphp/snowflake ❄️ 雪花算法分布式唯一 ID 生成器 —— 64 位、趋势递增、零依赖。 ## 环境要求 - PHP >= 8.5 - 多实例自动分配 workerId 时需要 `ext-redis` - 协程环境建议安装 `workerman/workerman`(通过 `Timer::sleep` 让出事件循环) ## 安装 ```bash composer require fiberphp/snowflake ``` ## 快速开始 ```php 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: ```php $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](LICENSE)。