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,13 +18,100 @@ 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
 
-**ULID (Universally Unique Lexicographically Sortable Identifier):** A 128-bit identifier designed for high uniqueness and lexicographical sortability. It combines a timestamp component with random data, allowing for ordered IDs that can be generated rapidly and are human-readable, making it ideal for databases and distributed systems.
+### ULID (Universally Unique Lexicographically Sortable Identifier)
+A 128-bit identifier designed for high uniqueness and lexicographical sortability. It combines a timestamp component with random data, allowing for ordered IDs that can be generated rapidly and are human-readable, making it ideal for databases and distributed systems.
 
 ```php
 use Cycle\Annotated\Annotation\Column;
@@ -44,7 +130,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 +148,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;
@@ -78,7 +166,8 @@ class User
 }
 ```
 
-**UUID Version 3 (Name-based, MD5):** Created by hashing a namespace identifier and name using MD5, resulting in a deterministic UUID based on input data.
+### UUID Version 3 (Name-based, MD5)
+Created by hashing a namespace identifier and name using MD5, resulting in a deterministic UUID based on input data.
 
 ```php
 use Cycle\Annotated\Annotation\Column;
@@ -99,7 +188,8 @@ class User
 }
 ```
 
-**UUID Version 4 (Random):** Generated entirely from random or pseudo-random numbers, offering high unpredictability and uniqueness.
+### UUID Version 4 (Random)
+Generated entirely from random or pseudo-random numbers, offering high unpredictability and uniqueness.
 
 ```php
 use Cycle\Annotated\Annotation\Column;
@@ -116,7 +206,8 @@ class User
 }
 ```
 
-**UUID Version 5 (Name-based, SHA-1):** Similar to version 3 but uses SHA-1 hashing, providing a different deterministic UUID based on namespace and name.
+### UUID Version 5 (Name-based, SHA-1)
+Similar to version 3 but uses SHA-1 hashing, providing a different deterministic UUID based on namespace and name.
 
 ```php
 use Cycle\Annotated\Annotation\Column;
@@ -137,7 +228,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;
@@ -154,7 +246,8 @@ class User
 }
 ```
 
-**UUID Version 7 (Draft/Upcoming):** A newer proposal designed to incorporate sortable features based on Unix timestamp, enhancing performance in database indexing.
+### UUID Version 7 (Draft/Upcoming)
+A newer proposal designed to incorporate sortable features based on Unix timestamp, enhancing performance in database indexing.
 
 ```php
 use Cycle\Annotated\Annotation\Column;
@@ -171,7 +264,33 @@ class User
 }
 ```
 
-You can find more information about Entity behavior UUID [here](https://cycle-orm.dev/docs/entity-behaviors-identifier).
+## Global Configuration
+
+Some listener classes provide static functions allowing you to define global default values for various attributes. This approach helps you to:
+
+* Initialize defaults at a suitable point in your application's lifecycle.
+* Customize defaults dynamically based on environment-specific conditions.
+* Minimize redundancy by setting shared attribute values once, instead of repeatedly specifying them across entities.
+
+**Sample code:**
+
+```php
+use Cycle\ORM\Entity\Behavior\Identifier\Listener;
+
+Listener\SnowflakeGeneric::setDefaults($node, $epochOffset);
+Listener\SnowflakeDiscord::setDefaults($workerId, $processId);
+Listener\SnowflakeInstagram::setDefaults($shardId);
+Listener\SnowflakeMastodon::setDefaults($tableName);
+Listener\SnowflakeTwitter::setDefaults($machineId);
+
+Listener\Uuid1::setDefaults($node, $clockSeq);
+Listener\Uuid2::setDefaults($localDomain, $localIdentifier, $node, $clockSeq);
+Listener\Uuid3::setDefaults($namespace, $name);
+Listener\Uuid5::setDefaults($namespace, $name);
+Listener\Uuid6::setDefaults($node, $clockSeq);
+````
+
+You can find more information about Entity behavior Identifier [here](https://cycle-orm.dev/docs/entity-behaviors-identifier).
 
 ## License:
 

composer.json

@@ -41,7 +41,7 @@
     },
     "require": {
         "php": ">=8.2",
-        "cycle/entity-behavior": "^1.6",
+        "cycle/entity-behavior": "^1.7",
         "ramsey/identifier": "^0.1"
     },
     "require-dev": {