# 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-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FiberPHP Snowflake

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

## 环境要求

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

## 安装

```bash
composer require fiberphp-ext/snowflake
```

## 快速开始

```php
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）：

```php
$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](LICENSE)。