Skip to content

Commit 536462d

Browse files
author
github-ci
committed
update
1 parent bb8845d commit 536462d

20 files changed

+586
-576
lines changed

‎.github/workflows/composer-require-checker.yml‎

Lines changed: 0 additions & 36 deletions
This file was deleted.

‎.github/workflows/phpunit.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@ jobs:
99
fail-fast: false
1010
matrix:
1111
php_version:
12-
- 8.1
1312
- 8.2
1413
- 8.3
1514
- 8.4

‎README.md‎

Lines changed: 60 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,54 @@
11
# Symfony Snowflake Bundle
22

3+
[English](README.md) | [中文](README.zh-CN.md)
4+
35
[![Packagist](https://img.shields.io/packagist/v/tourze/symfony-snowflake-bundle.svg)](https://packagist.org/packages/tourze/symfony-snowflake-bundle)
6+
7+
[![PHP Version](https://img.shields.io/packagist/php-v/tourze/symfony-snowflake-bundle.svg)](https://packagist.org/packages/tourze/symfony-snowflake-bundle)
8+
9+
[![Build Status](https://img.shields.io/github/actions/workflow/status/tourze/php-monorepo/ci.yml?branch=master)](https://github.com/tourze/php-monorepo/actions)
10+
11+
[![Coverage Status](https://img.shields.io/codecov/c/github/tourze/php-monorepo)](https://codecov.io/gh/tourze/php-monorepo)
12+
413
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
514

15+
## Table of Contents
16+
17+
- [Introduction](#introduction)
18+
- [Features](#features)
19+
- [Installation](#installation)
20+
- [Requirements](#requirements)
21+
- [Install via Composer](#install-via-composer)
22+
- [Quick Start](#quick-start)
23+
- [1. Register the Bundle (if not auto-discovered)](#1-register-the-bundle-if-not-auto-discovered)
24+
- [2. Generate a Snowflake ID](#2-generate-a-snowflake-id)
25+
- [Usage](#usage)
26+
- [Basic Usage](#basic-usage)
27+
- [ID Format and Structure](#id-format-and-structure)
28+
- [WorkerId Generation](#workerid-generation)
29+
- [Redis-Based Sequence Resolver](#redis-based-sequence-resolver)
30+
- [Configuration](#configuration)
31+
- [Advanced Usage](#advanced-usage)
32+
- [Custom Sequence Resolver](#custom-sequence-resolver)
33+
- [Best Practices](#best-practices)
34+
- [Potential Pitfalls](#potential-pitfalls)
35+
- [Contributing](#contributing)
36+
- [License](#license)
37+
638
## Introduction
739

8-
A high-performance, distributed Snowflake ID generator bundle for Symfony applications. This bundle implements Twitter's Snowflake algorithm to generate unique, time-ordered, 64-bit IDs for distributed systems. It is designed for scenarios requiring globally unique IDs under high concurrency.
40+
A high-performance, distributed Snowflake ID generator bundle for Symfony applications. This bundle implements
41+
Twitter's Snowflake algorithm to generate unique, time-ordered, 64-bit IDs for distributed systems. It is
42+
designed for scenarios requiring globally unique IDs under high concurrency.
943

1044
## Features
1145

1246
- Generates 64-bit unique IDs based on [godruoyi/php-snowflake](https://github.com/godruoyi/php-snowflake) library
1347
- Built-in Redis sequence resolver to ensure uniqueness in high-concurrency environments
1448
- Auto-generates WorkerId based on hostname for distributed scenario support
1549
- Zero configuration required for basic usage
16-
- Fully compatible with Symfony 6.4/7.1+
50+
- Fully compatible with Symfony 7.3+
51+
- Graceful fallback from Redis to RandomSequenceResolver when Redis is unavailable
1752
- Autowiring support for easy integration with Symfony services
1853
- Thread-safe ID generation
1954
- Time-ordered IDs for efficient database indexing
@@ -23,7 +58,7 @@ A high-performance, distributed Snowflake ID generator bundle for Symfony applic
2358
### Requirements
2459

2560
- PHP >= 8.1
26-
- Symfony >= 6.4
61+
- Symfony >= 7.3
2762
- Redis (recommended for distributed sequence safety)
2863

2964
### Install via Composer
@@ -113,17 +148,20 @@ This ensures different server instances generally get different WorkerIds withou
113148

114149
### Redis-Based Sequence Resolver
115150

116-
When `snc/redis-bundle` is installed and configured in your application, the Snowflake bundle automatically uses Redis for sequence distribution, which provides:
117-
151+
When Redis is available, the bundle automatically uses `RedisSequenceResolver` for:
118152
- Enhanced uniqueness guarantees under high concurrency
119153
- Improved resistance to clock drift
120154
- Better distribution of IDs across multiple instances
121155

156+
When Redis is unavailable, it gracefully falls back to `RandomSequenceResolver` to ensure service availability.
157+
122158
## Configuration
123159

124160
For basic usage, no extra configuration is required. The bundle works with sensible defaults.
125161

126-
### Advanced Configuration
162+
## Advanced Usage
163+
164+
### Custom Sequence Resolver
127165

128166
For more advanced scenarios, you may extend the `ResolverFactory` to provide a custom sequence resolver:
129167

@@ -151,19 +189,31 @@ Then register your custom factory in your service configuration.
151189

152190
- **Redis in Production**: Always use Redis in production environments for sequence distribution
153191
- **Clock Synchronization**: Ensure your server clocks are synchronized with NTP
154-
- **Worker ID Management**: For large distributed deployments, consider implementing a centralized WorkerId assignment mechanism
155-
- **ID Storage**: Store Snowflake IDs as `BIGINT` in databases (or strings if your DB doesn't support 64-bit integers)
192+
- **Worker ID Management**: For large distributed deployments, consider implementing a centralized WorkerId
193+
assignment mechanism
194+
- **ID Storage**: Store Snowflake IDs as `BIGINT` in databases (or strings if your DB doesn't support
195+
64-bit integers)
156196
- **Benchmarking**: Test performance in your environment as high throughput may require tuning
157197

158198
## Potential Pitfalls
159199

160200
- **Clock Moving Backwards**: If server time moves backward due to NTP adjustments, duplicate IDs might be generated
161-
- **Worker ID Conflicts**: In very large deployments, hostname-based WorkerId generation might lead to conflicts
201+
- **Worker ID Conflicts**: In very large deployments, hostname-based WorkerId generation might lead to
202+
conflicts
162203
- **Performance without Redis**: Without Redis, high concurrency might lead to duplicates under extreme circumstances
163204

205+
## Changelog
206+
207+
### 0.0.x
208+
- Initial release with Snowflake ID generation support
209+
- Redis-based sequence resolver with graceful fallback
210+
- Automatic WorkerId generation based on hostname
211+
- Full Symfony 7.3+ integration with autowiring support
212+
164213
## Contributing
165214

166-
Issues and pull requests are welcome! Please visit the [GitHub repository](https://github.com/tourze/symfony-snowflake-bundle) to contribute.
215+
Issues and pull requests are welcome! Please visit the
216+
[GitHub repository](https://github.com/tourze/php-monorepo) to contribute.
167217

168218
## License
169219

‎README.zh-CN.md‎

Lines changed: 66 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,54 @@
11
# Symfony Snowflake 雪花 ID 生成器
22

3+
[English](README.md) | [中文](README.zh-CN.md)
4+
35
[![Packagist](https://img.shields.io/packagist/v/tourze/symfony-snowflake-bundle.svg)](https://packagist.org/packages/tourze/symfony-snowflake-bundle)
6+
7+
[![PHP Version](https://img.shields.io/packagist/php-v/tourze/symfony-snowflake-bundle.svg)](https://packagist.org/packages/tourze/symfony-snowflake-bundle)
8+
9+
[![Build Status](https://img.shields.io/github/actions/workflow/status/tourze/php-monorepo/ci.yml?branch=master)](https://github.com/tourze/php-monorepo/actions)
10+
11+
[![Coverage Status](https://img.shields.io/codecov/c/github/tourze/php-monorepo)](https://codecov.io/gh/tourze/php-monorepo)
12+
413
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
514

15+
## 目录
16+
17+
- [项目简介](#项目简介)
18+
- [功能特性](#功能特性)
19+
- [安装方法](#安装方法)
20+
- [环境要求](#环境要求)
21+
- [通过 Composer 安装](#通过-composer-安装)
22+
- [快速开始](#快速开始)
23+
- [1. 注册 Bundle（如未自动发现）](#1-注册-bundle如未自动发现)
24+
- [2. 生成雪花 ID](#2-生成雪花-id)
25+
- [基本用法](#基本用法)
26+
- [基本使用](#基本使用)
27+
- [ID 格式与结构](#id-格式与结构)
28+
- [WorkerId 生成逻辑](#workerid-生成逻辑)
29+
- [基于 Redis 的序列分配器](#基于-redis-的序列分配器)
30+
- [高级用法](#高级用法)
31+
- [自定义序列分配器](#自定义序列分配器)
32+
- [配置说明](#配置说明)
33+
- [监控与调试](#监控与调试)
34+
- [最佳实践](#最佳实践)
35+
- [注意事项](#注意事项)
36+
- [贡献指南](#贡献指南)
37+
- [许可协议](#许可协议)
38+
639
## 项目简介
740

8-
为 Symfony 应用提供高性能、分布式的雪花（Snowflake）ID 生成服务。本模块实现了 Twitter 的雪花算法，用于生成有序、唯一的 64 位 ID，特别适用于分布式系统和需要全局唯一 ID 的高并发场景。
41+
为 Symfony 应用提供高性能、分布式的雪花（Snowflake）ID 生成服务。本模块实现了 Twitter 的雪花算法，
42+
用于生成有序、唯一的 64 位 ID，特别适用于分布式系统和需要全局唯一 ID 的高并发场景。
943

1044
## 功能特性
1145

1246
- 基于 [godruoyi/php-snowflake](https://github.com/godruoyi/php-snowflake) 库实现，生成 64 位全局唯一 ID
1347
- 内置 Redis 序列分配器，确保高并发环境下的唯一性
1448
- 自动基于主机名生成 WorkerId，支持分布式部署场景
1549
- 零配置即可使用，简单直观
16-
- 完全兼容 Symfony 6.4/7.1+
50+
- 完全兼容 Symfony 7.3+
51+
- Redis 不可用时优雅降级到 RandomSequenceResolver
1752
- 支持 Symfony 自动注入，便于与服务集成
1853
- 线程安全的 ID 生成机制
1954
- 生成的 ID 具有时间顺序性，利于数据库索引优化
@@ -23,7 +58,7 @@
2358
### 环境要求
2459

2560
- PHP >= 8.1
26-
- Symfony >= 6.4
61+
- Symfony >= 7.3
2762
- Redis（推荐用于分布式序列安全）
2863

2964
### 通过 Composer 安装
@@ -32,7 +67,7 @@
3267
composer require tourze/symfony-snowflake-bundle
3368
```
3469

35-
## 快速上手
70+
## 快速开始
3671

3772
### 1. 注册 Bundle（如未自动发现）
3873

@@ -74,9 +109,9 @@ class ProductService
74109
}
75110
```
76111

77-
## 使用说明
112+
## 基本用法
78113

79-
### 基本用法
114+
### 基本使用
80115

81116
通过依赖注入引入 Snowflake 服务，然后调用 `id()` 方法：
82117

@@ -113,17 +148,18 @@ $workerId = crc32(gethostname()) % 32; // 返回 0-31 之间的值
113148

114149
### 基于 Redis 的序列分配器
115150

116-
当应用中安装并配置了 `snc/redis-bundle` 后，Snowflake 模块会自动使用 Redis 进行序列分配，提供：
117-
151+
当 Redis 可用时，模块自动使用 `RedisSequenceResolver` 提供：
118152
- 高并发环境下增强的唯一性保证
119153
- 更好地抵抗时钟漂移
120154
- 在多实例间更均匀地分配 ID
121155

122-
## 配置说明
156+
当 Redis 不可用时，优雅降级到 `RandomSequenceResolver` 以确保服务可用性。
157+
158+
## 高级用法
123159

124160
基本使用场景下无需额外配置，模块采用合理的默认设置。
125161

126-
### 高级配置
162+
### 自定义序列分配器
127163

128164
对于更高级的场景，可以扩展 `ResolverFactory` 来提供自定义序列分配器：
129165

@@ -147,12 +183,21 @@ class CustomResolverFactory extends ResolverFactory
147183

148184
然后在服务配置中注册自定义工厂。
149185

186+
## 配置说明
187+
188+
基本使用场景下无需额外配置，模块采用合理的默认设置。
189+
190+
### 监控与调试
191+
192+
在生产环境中，建议监控 ID 生成的性能和唯一性，确保系统正常运行。
193+
150194
## 最佳实践
151195

152196
- **生产环境使用 Redis**：始终在生产环境中使用 Redis 进行序列分配
153197
- **时钟同步**：确保服务器时钟通过 NTP 保持同步
154198
- **WorkerId 管理**：对于大型分布式部署，考虑实现集中式 WorkerId 分配机制
155-
- **ID 存储**：在数据库中使用 `BIGINT` 类型存储雪花 ID（如果数据库不支持 64 位整数，则使用字符串）
199+
- **ID 存储**：在数据库中使用 `BIGINT` 类型存储雪花 ID（如果数据库不支持 64 位整数，
200+
则使用字符串）
156201
- **性能测试**：在您的环境中进行性能测试，高吞吐量可能需要调优
157202

158203
## 注意事项
@@ -161,9 +206,18 @@ class CustomResolverFactory extends ResolverFactory
161206
- **WorkerId 冲突**：在非常大的部署中，基于主机名的 WorkerId 生成可能导致冲突
162207
- **无 Redis 时的性能**：没有 Redis 的情况下，极端高并发可能导致重复
163208

209+
## 更新日志
210+
211+
### 0.0.x
212+
- 初始版本，支持雪花 ID 生成
213+
- 基于 Redis 的序列分配器，支持优雅降级
214+
- 基于主机名自动生成 WorkerId
215+
- 完整的 Symfony 7.3+ 集成，支持自动注入
216+
164217
## 贡献指南
165218

166-
欢迎提交 Issue 和 Pull Request！请访问 [GitHub 仓库](https://github.com/tourze/symfony-snowflake-bundle) 参与贡献。
219+
欢迎提交 Issue 和 Pull Request！请访问
220+
[GitHub 仓库](https://github.com/tourze/php-monorepo) 参与贡献。
167221

168222
## 许可协议
169223

‎composer.json‎

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,33 @@
11
{
22
"name": "tourze/symfony-snowflake-bundle",
3-
"description": "雪花ID模块",
3+
"description": "Symfony Bundle for Snowflake ID generation with Redis support",
44
"type": "symfony-bundle",
55
"license": "MIT",
66
"require": {
7-
"php": "^8.1",
87
"godruoyi/php-snowflake": "^3.1.1",
9-
"snc/redis-bundle": "^4.8",
10-
"symfony/config": "^6.4",
11-
"symfony/console": "^6.4",
12-
"symfony/dependency-injection": "^6.4",
13-
"symfony/event-dispatcher": "^6.4",
14-
"symfony/expression-language": "^6.4",
15-
"symfony/framework-bundle": "^6.4",
16-
"symfony/http-foundation": "^6.4",
17-
"symfony/http-kernel": "^6.4",
18-
"symfony/messenger": "^6.4",
19-
"symfony/property-access": "^6.4",
20-
"symfony/string": "^6.4",
21-
"symfony/yaml": "^6.4 || ^7.1",
22-
"tourze/bundle-dependency": "0.0.*",
23-
"tourze/symfony-integration-test-kernel": "0.0.*"
8+
"symfony/config": "^7.3",
9+
"symfony/console": "^7.3",
10+
"symfony/dependency-injection": "^7.3",
11+
"symfony/event-dispatcher": "^7.3",
12+
"symfony/expression-language": "^7.3",
13+
"symfony/framework-bundle": "^7.3",
14+
"symfony/http-foundation": "^7.3",
15+
"symfony/http-kernel": "^7.3",
16+
"symfony/messenger": "^7.3",
17+
"symfony/property-access": "^7.3",
18+
"symfony/string": "^7.3",
19+
"symfony/yaml": "^7.3",
20+
"tourze/bundle-dependency": "1.*",
21+
"tourze/redis-dedicated-connection-bundle": "0.0.*",
22+
"tourze/symfony-dependency-service-loader": "0.0.*"
2423
},
2524
"require-dev": {
2625
"phpstan/phpstan": "^2.1",
27-
"phpunit/phpunit": "^10.0",
28-
"symfony/phpunit-bridge": "^6.4"
26+
"phpunit/phpunit": "^11.5",
27+
"symfony/phpunit-bridge": "^7.3",
28+
"tourze/phpunit-symfony-kernel-test": "0.0.*",
29+
"tourze/phpunit-symfony-unit-test": "0.0.*",
30+
"tourze/symfony-testing-framework": "0.0.*"
2931
},
3032
"autoload": {
3133
"psr-4": {

0 commit comments

Comments
 (0)