Doctrine Snowflake Id Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — that framing matters more than anything else on this page.

• In Symfony: composer require jeancodogno/doctrine-snowflake-id-bundle, register the bundle in config/bundles.php, set doctrine_snowflake_id.datacenter_id and doctrine_snowflake_id.worker_id (almost always via env vars), then tag your entity/document ID property with the #[SnowflakeId] attribute. Drop the column's AUTO_INCREMENT/generatedValue strategy in the migration.
• In Laravel: there is no service provider, no config publish tag, and no Eloquent integration. You have two realistic paths: (1) use Doctrine via laravel-doctrine/orm and register the bundle's listener + attribute driver manually, or (2) skip the bundle entirely and use godruoyi/php-snowflake inside an Eloquent creating observer. Path 2 is the sane default for a typical Laravel app.

Where to look first in the source: the SnowflakeId attribute class, the Doctrine event listener (the only real logic), and the Configuration/Extension classes for the exact config keys and defaults.

First use case: replacing auto-increment IDs on a high-write table (orders, events, messages) where you want IDs generated in the app, sortable by time, and safe to produce without a DB round trip.

Implementation Patterns

• Attribute on the ID property, nothing else. The listener populates the ID before persist. Don't set it in the constructor or a factory — you'll fight the listener and lose the monotonicity guarantees.
• Per-instance worker IDs. worker_id/datacenter_id must be unique per process (pod, container, host). Wire them from HOSTNAME, a K8s downward-API field, or an env var rendered at deploy time. Hardcoding 0 works in dev and corrupts you in prod.
• Both ORM and MongoDB ODM are supported as of 1.0.0, with separate wiring for each. If you're on Doctrine ODM, that's the release that makes this usable at all.
• API responses: snowflake IDs are 64-bit ints. Cast to string in resources/serializers or JavaScript clients will silently round them (Number.MAX_SAFE_INTEGER).
• Schema: BIGINT UNSIGNED (or string if you're paranoid about JS/PHP interop). Remember to drop the AUTO_INCREMENT and any ->id() default from migrations.
• Testing: pin worker_id/datacenter_id in phpunit.xml so IDs are deterministic-ish and tests don't depend on deploy config. The 1.0.0 listener tests are a decent reference for asserting "ID was assigned and is non-null" without asserting exact values.
• In Laravel with Doctrine: register the listener on the postLoad/prePersist events through a small service provider and bind the config as a plain array — the bundle's autowiring won't happen for you.

Gotchas and Tips

• Breaking change: 1.0.0 renames the attribute "for clarity." If you were on 0.1.0, update every entity/document. There is no documented alias/shim.
• Node ID collisions are the classic failure mode — duplicated IDs across replicas, surfacing much later as unique-constraint violations or silently overwritten documents. Validate uniqueness at boot and fail fast.
• Clock skew backwards can produce duplicate or out-of-order IDs. Keep NTP healthy on hosts; treat a container clock jump as an incident.
• PHP must be 64-bit. Snowflakes exceed 32-bit PHP_INT_MAX; on a 32-bit build you get float coercion and corrupted IDs.
• The IDs are time-sortable and roughly guessable (timestamp + node + sequence). Don't use them as public unguessable tokens — pair with a random slug/UUID for anything user-facing and authorization-relevant.
• Config quirk: the attribute is autowired to read snowflake configuration (per the 1.0.0 refactor). If the config keys aren't present under the expected bundle key, you get a runtime failure at persist time rather than a clear boot-time error. Assert config presence in a small boot check.
• No Laravel service provider, no config/snowflake.php. Don't copy-paste Symfony docs into a Laravel app expecting it to work; budget a day for wiring or take the php-snowflake route.
• Extension point: wrap generation behind your own IdGenerator interface rather than calling the attribute everywhere. When you outgrow the bundle (or move off Doctrine), you swap one binding instead of touching every entity.
• Debugging: when an ID comes back null, check listener registration before the attribute — a missing doctrine.event_listener tag is the usual culprit, not the attribute itself.