README

👁 PHP Version Require
👁 Latest Version
👁 License
👁 Build Status
👁 Coverage Status
👁 Total Downloads

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.