Snowflake identifier

README.md

@@ -1,7 +1,6 @@
 # Cycle ORM Entity Behavior Identifier
-[![Latest Stable Version](https://poser.pugx.org/cycle/entity-behavior-Identifier/version)](https://packagist.org/packages/cycle/entity-behavior-identifier)
+[![Latest Stable Version](https://poser.pugx.org/cycle/entity-behavior-identifier/version)](https://packagist.org/packages/cycle/entity-behavior-identifier)
 [![Build Status](https://github.com/cycle/entity-behavior-identifier/workflows/build/badge.svg)](https://github.com/cycle/entity-behavior-identifier/actions)
-[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/cycle/entity-behavior-identifier/badges/quality-score.png?b=1.x)](https://scrutinizer-ci.com/g/cycle/entity-behavior-identifier/?branch=1.x)
 [![Codecov](https://codecov.io/gh/cycle/entity-behavior-identifier/graph/badge.svg)](https://codecov.io/gh/cycle/entity-behavior)
 <a href="https://discord.gg/TFeEmCs"><img src="https://img.shields.io/badge/discord-chat-magenta.svg"></a>
 
@@ -19,9 +18,95 @@ composer require cycle/entity-behavior-identifier
 
 ## Snowflake Examples
 
-**Snowflake:** A distributed ID generation system developed by Twitter that produces 64-bit unique, sortable identifiers. Each ID encodes a timestamp, machine ID, and sequence number, enabling high-throughput, ordered ID creation suitable for large-scale distributed applications.
+### Generic
+A flexible Snowflake format that can use a node identifier and any epoch offset, suitable for various applications requiring unique identifiers. Default values for `node` and `epochOffset` can be defined globally via the `\Cycle\ORM\Entity\Behavior\Identifier\Listener\SnowflakeGeneric::setDefaults()` method.
 
-> **Note:** Support for Snowflake identifiers will arrive soon, stay tuned.
+```php
+use Cycle\Annotated\Annotation\Column;
+use Cycle\Annotated\Annotation\Entity;
+use Cycle\ORM\Entity\Behavior\Identifier;
+use Ramsey\Identifier\Snowflake;
+
+#[Entity]
+#[Identifier\SnowflakeGeneric(field: 'id', node: 1, epochOffset: 1738265600000)]
+class User
+{
+    #[Column(type: 'snowflake', primary: true)]
+    private Snowflake $id;
+}
+```
+
+### Discord
+Snowflake identifier for Discord's platform (voice, text, video), starting from epoch `2015-01-01`. Can incorporate a worker and process ID's to generate distinct Snowflakes. Default values for `workerId` and `processId` can be defined globally via the `\Cycle\ORM\Entity\Behavior\Identifier\Listener\SnowflakeDiscord::setDefaults()` method.
+
+```php
+use Cycle\Annotated\Annotation\Column;
+use Cycle\Annotated\Annotation\Entity;
+use Cycle\ORM\Entity\Behavior\Identifier;
+use Ramsey\Identifier\Snowflake;
+
+#[Entity]
+#[Identifier\SnowflakeDiscord(field: 'id', workerId: 12, processId: 24)]
+class User
+{
+    #[Column(type: 'snowflake', primary: true)]
+    private Snowflake $id;
+}
+```
+
+### Instagram
+Snowflake identifier for Instagram's photo and video sharing platform, with an epoch starting at `2011-08-24`. Can incorporate a shard ID to generate distinct Snowflakes. Default values for `shardId` can be defined globally via the `\Cycle\ORM\Entity\Behavior\Identifier\Listener\SnowflakeInstagram::setDefaults()` method.
+
+```php
+use Cycle\Annotated\Annotation\Column;
+use Cycle\Annotated\Annotation\Entity;
+use Cycle\ORM\Entity\Behavior\Identifier;
+use Ramsey\Identifier\Snowflake;
+
+#[Entity]
+#[Identifier\SnowflakeInstagram(field: 'id', shardId: 16)]
+class User
+{
+    #[Column(type: 'snowflake', primary: true)]
+    private Snowflake $id;
+}
+```
+
+### Mastodon
+Snowflake identifier for Mastodon's decentralized social network, generated within a database to ensure uniqueness and approximate order within 1ms. Can include a table name for distinct sequences per table; IDs are unique on a single database but not guaranteed across multiple machines. Default values for `tableName` can be defined globally via the `\Cycle\ORM\Entity\Behavior\Identifier\Listener\SnowflakeMastodon::setDefaults()` method.
+
+```php
+use Cycle\Annotated\Annotation\Column;
+use Cycle\Annotated\Annotation\Entity;
+use Cycle\ORM\Entity\Behavior\Identifier;
+use Ramsey\Identifier\Snowflake;
+
+#[Entity]
+#[Identifier\SnowflakeMastodon(field: 'id', tableName: 'users')]
+class User
+{
+    #[Column(type: 'snowflake', primary: true)]
+    private Snowflake $id;
+}
+```
+
+### Twitter
+Snowflake identifier for Twitter (X), beginning from `2010-11-04`. Can incorporate a machine ID to generate distinct Snowflakes. Default values for `machineId` can be defined globally via the `\Cycle\ORM\Entity\Behavior\Identifier\Listener\SnowflakeTwitter::setDefaults()` method.
+
+```php
+use Cycle\Annotated\Annotation\Column;
+use Cycle\Annotated\Annotation\Entity;
+use Cycle\ORM\Entity\Behavior\Identifier;
+use Ramsey\Identifier\Snowflake;
+
+#[Entity]
+#[Identifier\SnowflakeTwitter(field: 'id', machineId: 30)]
+class User
+{
+    #[Column(type: 'snowflake', primary: true)]
+    private Snowflake $id;
+}
+```
 
 ## ULID Examples
 
@@ -44,7 +129,8 @@ class User
 
 ## UUID Examples
 
-**UUID Version 1 (Time-based):** Generated using the current timestamp and the MAC address of the computer, ensuring unique identification based on time and hardware.
+### UUID Version 1 (Time-based)
+Generated using the current timestamp and the MAC address of the computer, ensuring unique identification based on time and hardware. Default values for `node` and `clockSeq` can be defined globally via the `\Cycle\ORM\Entity\Behavior\Identifier\Listener\Uuid1::setDefaults()` method.
 
 ```php
 use Cycle\Annotated\Annotation\Column;
@@ -61,7 +147,8 @@ class User
 }
 ```
 
-**UUID Version 2 (DCE Security):** Similar to version 1 but includes a local identifier such as a user ID or group ID, primarily used in DCE security contexts.
+### UUID Version 2 (DCE Security)
+Similar to version 1 but includes a local identifier such as a user ID or group ID, primarily used in DCE security contexts. Default values for `localDomain`, `localIdentifier`, `node` and `clockSeq` can be defined globally via the `\Cycle\ORM\Entity\Behavior\Identifier\Listener\Uuid2::setDefaults()` method.
 
 ```php
 use Cycle\Annotated\Annotation\Column;
@@ -137,7 +224,8 @@ class User
 }
 ```
 
-**UUID Version 6 (Draft/Upcoming):** An experimental or proposed version focused on improving time-based UUIDs with more sortable properties (not yet widely adopted).
+### UUID Version 6 (Draft/Upcoming)
+An experimental or proposed version focused on improving time-based UUIDs with more sortable properties (not yet widely adopted). Default values for `node` and `clockSeq` can be defined globally via the `\Cycle\ORM\Entity\Behavior\Identifier\Listener\Uuid6::setDefaults()` method.
 
 ```php
 use Cycle\Annotated\Annotation\Column;
@@ -171,7 +259,7 @@ class User
 }
 ```
 
-You can find more information about Entity behavior UUID [here](https://cycle-orm.dev/docs/entity-behaviors-identifier).
+You can find more information about Entity behavior Identifier [here](https://cycle-orm.dev/docs/entity-behaviors-identifier).
 
 ## License:
 

src/Listener/BaseUuid.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\ORM\Entity\Behavior\Identifier\Listener;
+
+use Cycle\ORM\Entity\Behavior\Attribute\Listen;
+use Cycle\ORM\Entity\Behavior\Event\Mapper\Command\OnCreate;
+
+abstract class BaseUuid
+{
+    /**
+     * @param non-empty-string $field The name of the field to store the UUID
+     * @param bool $nullable Indicates whether the UUID can be null
+     */
+    public function __construct(
+        private readonly string $field,
+        private readonly bool $nullable = false,
+    ) {}
+
+    #[Listen(OnCreate::class)]
+    public function __invoke(OnCreate $event): void
+    {
+        if ($this->nullable || isset($event->state->getData()[$this->field])) {
+            return;
+        }
+
+        $event->state->register($this->field, $this->createValue());
+    }
+
+    abstract protected function createValue(): \Ramsey\Identifier\Uuid;
+}

src/Listener/Snowflake.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\ORM\Entity\Behavior\Identifier\Listener;
+
+use Cycle\ORM\Entity\Behavior\Attribute\Listen;
+use Cycle\ORM\Entity\Behavior\Event\Mapper\Command\OnCreate;
+
+abstract class Snowflake
+{
+    /**
+     * @param non-empty-string $field The name of the field to store the Snowflake identifier
+     * @param bool $nullable Indicates whether the Snowflake identifier can be null
+     */
+    public function __construct(
+        private readonly string $field,
+        private readonly bool $nullable = false,
+    ) {}
+
+    #[Listen(OnCreate::class)]
+    public function __invoke(OnCreate $event): void
+    {
+        if ($this->nullable || isset($event->state->getData()[$this->field])) {
+            return;
+        }
+
+        $event->state->register($this->field, $this->createValue());
+    }
+
+    abstract protected function createValue(): \Ramsey\Identifier\Snowflake;
+}