README

English | 中文

Table of Contents

• Introduction
• Features
• Installation
  • Requirements
  • Install via Composer
• Quick Start
  • 1. Register the Bundle (if not auto-discovered)
  • 2. Generate a Snowflake ID
• Usage
  • Basic Usage
  • ID Format and Structure
  • WorkerId Generation
  • Redis-Based Sequence Resolver
• Configuration
• Advanced Usage
  • Custom Sequence Resolver
• Best Practices
• Potential Pitfalls
• Contributing
• License

Introduction

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.

Features

• Generates 64-bit unique IDs based on godruoyi/php-snowflake library
• Built-in Redis sequence resolver to ensure uniqueness in high-concurrency environments
• Auto-generates WorkerId based on hostname for distributed scenario support
• Zero configuration required for basic usage
• Fully compatible with Symfony 7.3+
• Graceful fallback from Redis to RandomSequenceResolver when Redis is unavailable
• Autowiring support for easy integration with Symfony services
• Thread-safe ID generation
• Time-ordered IDs for efficient database indexing

Installation

Requirements

• PHP >= 8.1
• Symfony >= 7.3
• Redis (recommended for distributed sequence safety)

Install via Composer

composer require tourze/symfony-snowflake-bundle

Quick Start

1. Register the Bundle (if not auto-discovered)

Add to config/bundles.php:

return [
    // ...
    Tourze\SnowflakeBundle\SnowflakeBundle::class => ['all' => true],
];

2. Generate a Snowflake ID

Inject the Snowflake service into your service or controller:

<?php

namespace App\Service;

use Tourze\SnowflakeBundle\Service\Snowflake;

class ProductService
{
    public function __construct(
        private readonly Snowflake $snowflake
    ) {
    }

    public function createProduct(): int|string
    {
        // Generate a unique ID for your new product
        $uniqueId = $this->snowflake->id();
        
        // Use the ID in your application logic
        return $uniqueId;
    }
}

Usage

Basic Usage

Simply inject the Snowflake service and call the id() method:

// Inject via constructor
public function __construct(private readonly Snowflake $snowflake) {}

// Generate a unique ID
$id = $this->snowflake->id();

ID Format and Structure

The generated ID is a 64-bit integer with the following structure:

• 41 bits for timestamp (milliseconds since the epoch or custom epoch)
• 10 bits for worker ID (machine ID)
• 12 bits for sequence number (per millisecond counter)

This structure allows for:

• ~69 years of unique timestamps from custom epoch
• 1024 different worker IDs
• 4096 IDs per millisecond per worker

WorkerId Generation

By default, the WorkerId is automatically derived from the hostname using a CRC32 hash modulo operation:

$workerId = crc32(gethostname()) % 32; // Returns a value between 0-31

This ensures different server instances generally get different WorkerIds without manual configuration.

Redis-Based Sequence Resolver

When Redis is available, the bundle automatically uses RedisSequenceResolver for:

• Enhanced uniqueness guarantees under high concurrency
• Improved resistance to clock drift
• Better distribution of IDs across multiple instances

When Redis is unavailable, it gracefully falls back to RandomSequenceResolver to ensure service availability.

Configuration

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

Advanced Usage

Custom Sequence Resolver

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

<?php

namespace App\Service;

use Godruoyi\Snowflake\SequenceResolver;
use Tourze\SnowflakeBundle\Service\ResolverFactory;

class CustomResolverFactory extends ResolverFactory
{
    public function resolver(): SequenceResolver
    {
        // Your custom resolver implementation
        return new YourCustomSequenceResolver();
    }
}

Then register your custom factory in your service configuration.

Best Practices

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

Potential Pitfalls

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

Changelog

0.0.x

• Initial release with Snowflake ID generation support
• Redis-based sequence resolver with graceful fallback
• Automatic WorkerId generation based on hostname
• Full Symfony 7.3+ integration with autowiring support

Contributing

Issues and pull requests are welcome! Please visit the GitHub repository to contribute.

License

This bundle is available under the MIT License. See the LICENSE file for more information.