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,90 @@ 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 class `Cycle\ORM\Entity\Behavior\Identifier\Defaults\SnowflakeGeneric`.
 
-> **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 class `Cycle\ORM\Entity\Behavior\Identifier\Defaults\SnowflakeDiscord`.
+
+```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 class `Cycle\ORM\Entity\Behavior\Identifier\Defaults\SnowflakeInstagram`.
+
+```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 class `Cycle\ORM\Entity\Behavior\Identifier\Defaults\SnowflakeMastodon`.
+
+```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 class `Cycle\ORM\Entity\Behavior\Identifier\Defaults\SnowflakeTwitter`.
+
+```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 +124,7 @@ 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 class `Cycle\ORM\Entity\Behavior\Identifier\Defaults\Uuid1`.
 
 ```php
 use Cycle\Annotated\Annotation\Column;
@@ -61,7 +141,7 @@ 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 class `Cycle\ORM\Entity\Behavior\Identifier\Defaults\Uuid2`.
 
 ```php
 use Cycle\Annotated\Annotation\Column;
@@ -137,7 +217,7 @@ 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 class `Cycle\ORM\Entity\Behavior\Identifier\Defaults\Uuid6`.
 
 ```php
 use Cycle\Annotated\Annotation\Column;
@@ -171,7 +251,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/Defaults/SnowflakeDiscord.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\ORM\Entity\Behavior\Identifier\Defaults;
+
+final class SnowflakeDiscord
+{
+    private static int $workerId = 0;
+    private static int $processId = 0;
+
+    public static function getWorkerId(): int
+    {
+        return self::$workerId;
+    }
+
+    public static function setWorkerId(int $workerId): void
+    {
+        self::$workerId = $workerId;
+    }
+
+    public static function getProcessId(): int
+    {
+        return self::$processId;
+    }
+
+    public static function setProcessId(int $processId): void
+    {
+        self::$processId = $processId;
+    }
+}

src/Defaults/SnowflakeGeneric.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\ORM\Entity\Behavior\Identifier\Defaults;
+
+use Ramsey\Identifier\Snowflake\Epoch;
+
+final class SnowflakeGeneric
+{
+    private static int $node = 0;
+    private static Epoch|int $epochOffset = 0;
+
+    public static function getNode(): int
+    {
+        return self::$node;
+    }
+
+    public static function setNode(int $node): void
+    {
+        self::$node = $node;
+    }
+
+    public static function getEpochOffset(): Epoch|int
+    {
+        return self::$epochOffset;
+    }
+
+    public static function setEpochOffset(Epoch|int $epochOffset): void
+    {
+        self::$epochOffset = $epochOffset;
+    }
+}

src/Defaults/SnowflakeInstagram.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\ORM\Entity\Behavior\Identifier\Defaults;
+
+final class SnowflakeInstagram
+{
+    private static int $shardId = 0;
+
+    public static function getShardId(): int
+    {
+        return self::$shardId;
+    }
+
+    public static function setShardId(int $shardId): void
+    {
+        self::$shardId = $shardId;
+    }
+}

src/Defaults/SnowflakeMastodon.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\ORM\Entity\Behavior\Identifier\Defaults;
+
+final class SnowflakeMastodon
+{
+    /**
+     * @var non-empty-string|null
+     */
+    private static ?string $tableName = null;
+
+    /**
+     * @return non-empty-string|null
+     */
+    public static function getTableName(): ?string
+    {
+        return self::$tableName;
+    }
+
+    /**
+     * @param non-empty-string|null $tableName
+     */
+    public static function setTableName(?string $tableName): void
+    {
+        self::$tableName = $tableName;
+    }
+}