PHPackages                             tourze/doctrine-snowflake-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. tourze/doctrine-snowflake-bundle

ActiveLibrary

tourze/doctrine-snowflake-bundle
================================

为 Doctrine 实体提供雪花ID自动生成功能

1.1.1(4mo ago)027.4k2MITPHPCI passing

Since Mar 25Pushed 3mo ago1 watchersCompare

[ Source](https://github.com/tourze/doctrine-snowflake-bundle)[ Packagist](https://packagist.org/packages/tourze/doctrine-snowflake-bundle)[ RSS](/packages/tourze-doctrine-snowflake-bundle/feed)WikiDiscussions master Synced today

READMEChangelog (10)Dependencies (33)Versions (15)Used By (2)

Doctrine Snowflake Bundle
=========================

[](#doctrine-snowflake-bundle)

[![PHP Version Require](https://camo.githubusercontent.com/6713869277f2e76f00a2d94377ec35466cd69cdb67b59f681c37f61d1ce6f1e8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f746f75727a652f646f637472696e652d736e6f77666c616b652d62756e646c652f7068703f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tourze/doctrine-snowflake-bundle)[![Latest Version](https://camo.githubusercontent.com/dfcfe718ee1919752d11048de430afc081ddaffb5e287b33eeafa332536ac94b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f746f75727a652f646f637472696e652d736e6f77666c616b652d62756e646c652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tourze/doctrine-snowflake-bundle)[![License](https://camo.githubusercontent.com/24ab00f00e1f7a0525a65a615dabcb58d586e52ffa396b9d15538e96877b373b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f746f75727a652f646f637472696e652d736e6f77666c616b652d62756e646c652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tourze/doctrine-snowflake-bundle)[![Build Status](https://camo.githubusercontent.com/af73a22e7f4484b9646b494a7c69ee3a2f3cdab2ce32d47d9f53e77149bc76f8/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f746f75727a652f646f637472696e652d736e6f77666c616b652d62756e646c652f74657374732e796d6c3f6272616e63683d6d6173746572267374796c653d666c61742d737175617265)](https://github.com/tourze/doctrine-snowflake-bundle/actions)[![Coverage Status](https://camo.githubusercontent.com/bc9c7eb6d03d942ba785e12cf563e9c32eac645560aa5f493279bc6743ea8303/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f746f75727a652f646f637472696e652d736e6f77666c616b652d62756e646c653f7374796c653d666c61742d737175617265)](https://codecov.io/gh/tourze/doctrine-snowflake-bundle)[![Total Downloads](https://camo.githubusercontent.com/3f04f1312842d7a3691f751ffe2960ff130e3406908e168811cc3fe062679e4b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f746f75727a652f646f637472696e652d736e6f77666c616b652d62756e646c652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tourze/doctrine-snowflake-bundle)

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

[English](README.md) | [中文](README.zh-CN.md)

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
    - [Bundle Registration](#bundle-registration)
- [Quick Start](#quick-start)
    - [Method 1: Using SnowflakeKeyAware Trait (Recommended)](#method-1-using-snowflakekeyaware-trait-recommended)
    - [Method 2: Using SnowflakeColumn Attribute](#method-2-using-snowflakecolumn-attribute)
    - [Method 3: Manual ID Generator Configuration](#method-3-manual-id-generator-configuration)
- [Advanced Usage](#advanced-usage)
    - [Custom Configuration](#custom-configuration)
    - [Multiple Snowflake Properties](#multiple-snowflake-properties)
    - [Performance Tuning](#performance-tuning)
- [API Reference](#api-reference)
    - [SnowflakeColumn Attribute](#snowflakecolumn-attribute)
    - [SnowflakeKeyAware Trait](#snowflakekeyaware-trait)
    - [SnowflakeIdGenerator Service](#snowflakeidgenerator-service)
- [Testing](#testing)
- [Performance Considerations](#performance-considerations)
- [Contributing](#contributing)
- [License](#license)
- [Changelog](#changelog)

Features
--------

[](#features)

- **Snowflake ID Generation**: Based on [godruoyi/php-snowflake](https://github.com/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
------------

[](#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
------------

[](#installation)

```
composer require tourze/doctrine-snowflake-bundle
```

Configuration
-------------

[](#configuration)

### Bundle Registration

[](#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
-----------

[](#quick-start)

### Method 1: Using SnowflakeKeyAware Trait (Recommended)

[](#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

[](#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

[](#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
--------------

[](#advanced-usage)

### Custom Configuration

[](#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

[](#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

[](#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
-------------

[](#api-reference)

### SnowflakeColumn Attribute

[](#snowflakecolumn-attribute)

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

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

### SnowflakeKeyAware Trait

[](#snowflakekeyaware-trait)

Provides the following methods:

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

### SnowflakeIdGenerator Service

[](#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
-------

[](#testing)

Run the test suite:

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

Performance Considerations
--------------------------

[](#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
------------

[](#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
-------

[](#license)

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

Changelog
---------

[](#changelog)

See [Releases](https://packagist.org/packages/tourze/doctrine-snowflake-bundle#releases) for version history.

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance80

Actively maintained with recent releases

Popularity21

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~18 days

Recently: every ~39 days

Total

14

Last Release

124d ago

Major Versions

0.1.4 → 1.0.02025-10-31

### Community

Maintainers

![](https://www.gravatar.com/avatar/e354fdb316da535dfa8ba2e9193a473c403b6bc6fb9170778d1dc50e304c6e9d?d=identicon)[tourze](/maintainers/tourze)

---

Top Contributors

[![tourze](https://avatars.githubusercontent.com/u/13899502?v=4)](https://github.com/tourze "tourze (2 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tourze-doctrine-snowflake-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/tourze-doctrine-snowflake-bundle/health.svg)](https://phpackages.com/packages/tourze-doctrine-snowflake-bundle)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.5M596](/packages/sylius-sylius)[pimcore/pimcore

Content &amp; Product Management Framework (CMS/PIM/E-Commerce)

3.7k3.6M345](/packages/pimcore-pimcore)[oro/platform

Business Application Platform (BAP)

648132.0k71](/packages/oro-platform)[contao/core-bundle

Contao Open Source CMS

1231.6M2.0k](/packages/contao-core-bundle)[ec-cube/ec-cube

EC-CUBE EC open platform.

78427.0k1](/packages/ec-cube-ec-cube)[open-dxp/opendxp

Content &amp; Product Management Framework (CMS/PIM)

707.5k20](/packages/open-dxp-opendxp)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
