README

A Symfony bundle that provides Snowflake ID generation for Doctrine entities with distributed unique ID generation capabilities.

English | 中文

Table of Contents

• Features
• Requirements
• Installation
• Configuration
  • Bundle Registration
• Quick Start
  • Method 1: Using SnowflakeKeyAware Trait (Recommended)
  • Method 2: Using SnowflakeColumn Attribute
  • Method 3: Manual ID Generator Configuration
• Advanced Usage
  • Custom Configuration
  • Multiple Snowflake Properties
  • Performance Tuning
• API Reference
  • SnowflakeColumn Attribute
  • SnowflakeKeyAware Trait
  • SnowflakeIdGenerator Service
• Testing
• Performance Considerations
• Contributing
• License
• Changelog

Features

• Snowflake ID Generation: Based on godruoyi/php-snowflake
• Doctrine Integration: Auto-generate Snowflake IDs for Doctrine entity primary keys
• Attribute Support: Use #[SnowflakeColumn] attribute for custom ID properties
• Trait Support: Use SnowflakeKeyAware trait for automatic primary key generation
• Distributed Ready: WorkerId auto-generated by hostname, supporting distributed deployment
• Data Center ID: Automatically generated from entity class name for better ID distribution
• String Format: Returns IDs as strings to avoid JavaScript precision issues
• High Performance: Optimized for high concurrency scenarios

Requirements

• PHP 8.1 or newer
• Symfony 7.3 or newer
• Doctrine Bundle 2.13 or newer
• Doctrine ORM 3.0 or newer
• Doctrine DBAL 4.0 or newer
• tourze/symfony-snowflake-bundle

Installation

composer require tourze/doctrine-snowflake-bundle

Configuration

Bundle Registration

The bundle is automatically registered when using Symfony Flex. For manual installation:

// config/bundles.php
return [
    // ... other bundles
    Tourze\DoctrineSnowflakeBundle\DoctrineSnowflakeBundle::class => ['all' => true],
];

Quick Start

Method 1: Using SnowflakeKeyAware Trait (Recommended)

For primary key generation:

use Doctrine\ORM\Mapping as ORM;
use Tourze\DoctrineSnowflakeBundle\Traits\SnowflakeKeyAware;

#[ORM\Entity]
class YourEntity
{
    use SnowflakeKeyAware;
    
    #[ORM\Column(type: 'string', length: 255)]
    private string $name;
    
    // getter/setter methods...
}

Method 2: Using SnowflakeColumn Attribute

For custom ID properties (not primary keys):

use Doctrine\ORM\Mapping as ORM;
use Tourze\DoctrineSnowflakeBundle\Attribute\SnowflakeColumn;

#[ORM\Entity]
class YourEntity
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column(type: 'integer')]
    private int $id;
    
    #[SnowflakeColumn(prefix: 'ORDER_', length: 32)]
    #[ORM\Column(type: 'string', length: 32)]
    private string $orderId;
    
    // getter/setter methods...
}

Method 3: Manual ID Generator Configuration

use Doctrine\ORM\Mapping as ORM;
use Tourze\DoctrineSnowflakeBundle\Service\SnowflakeIdGenerator;

#[ORM\Entity]
class YourEntity
{
    #[ORM\Id]
    #[ORM\GeneratedValue(strategy: 'CUSTOM')]
    #[ORM\CustomIdGenerator(class: SnowflakeIdGenerator::class)]
    #[ORM\Column(type: 'bigint', nullable: false)]
    private string $id;
    
    // getter/setter methods...
}

Advanced Usage

Custom Configuration

You can customize the Snowflake ID generation behavior:

# config/packages/doctrine_snowflake.yaml
doctrine_snowflake:
    worker_id: 1  # Optional: Override auto-generated worker ID
    data_center_id: 1  # Optional: Override auto-generated data center ID

Multiple Snowflake Properties

You can use multiple Snowflake properties in a single entity:

#[ORM\Entity]
class Order
{
    use SnowflakeKeyAware;  // Primary key
    
    #[SnowflakeColumn(prefix: 'ORDER_', length: 32)]
    #[ORM\Column(type: 'string', length: 32)]
    private string $orderNumber;
    
    #[SnowflakeColumn(prefix: 'TXN_', length: 24)]
    #[ORM\Column(type: 'string', length: 24)]
    private string $transactionId;
}

Performance Tuning

For high-throughput applications:

• Use appropriate database indexes on Snowflake ID columns
• Consider using string column types to avoid integer overflow
• Monitor ID generation performance in distributed environments

API Reference

SnowflakeColumn Attribute

#[SnowflakeColumn(prefix: 'ORDER_', length: 32)]

• prefix: ID prefix (default: empty)
• length: Maximum ID length (default: 0, no limit)

SnowflakeKeyAware Trait

Provides the following methods:

• getId(): ?string - Get the entity ID
• setId(?string $id): void - Set the entity ID

SnowflakeIdGenerator Service

• Automatically generates unique Snowflake IDs
• Uses hostname for worker ID generation
• Uses entity class name for data center ID generation
• Preserves existing IDs when set manually

Testing

Run the test suite:

./vendor/bin/phpunit packages/doctrine-snowflake-bundle/tests

Performance Considerations

• Snowflake IDs are returned as strings to avoid JavaScript precision issues
• The generator uses CRC32 hash of class names for data center ID distribution
• Worker ID is generated from hostname for distributed deployments
• High concurrency scenarios are handled efficiently

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

License

The MIT License (MIT). Please see License File for more information.

Changelog

See Releases for version history.