Snowflake identifier

README.md

@@ -1,5 +1,5 @@
 # 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)
@@ -19,9 +19,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.
 
-> **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.
+
+```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.
+
+```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.
+
+```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.
+
+```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
 
@@ -171,7 +252,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/SnowflakeDiscord.php

@@ -0,0 +1,31 @@
+<?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;
+use Ramsey\Identifier\Snowflake\DiscordSnowflakeFactory;
+
+final class SnowflakeDiscord
+{
+    public function __construct(
+        private string $field = 'snowflake',
+        private int $workerId = 0,
+        private int $processId = 0,
+        private bool $nullable = false,
+    ) {}
+
+    #[Listen(OnCreate::class)]
+    public function __invoke(OnCreate $event): void
+    {
+        if ($this->nullable || isset($event->state->getData()[$this->field])) {
+            return;
+        }
+
+        $identifier = (new DiscordSnowflakeFactory($this->workerId, $this->processId))->create();
+
+        $event->state->register($this->field, $identifier);
+    }
+}

src/Listener/SnowflakeGeneric.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;
+use Ramsey\Identifier\Snowflake\Epoch;
+use Ramsey\Identifier\Snowflake\GenericSnowflakeFactory;
+
+final class SnowflakeGeneric
+{
+    public function __construct(
+        private string $field = 'snowflake',
+        private int $node = 0,
+        private Epoch|int $epochOffset = 0,
+        private bool $nullable = false,
+    ) {}
+
+    #[Listen(OnCreate::class)]
+    public function __invoke(OnCreate $event): void
+    {
+        if ($this->nullable || isset($event->state->getData()[$this->field])) {
+            return;
+        }
+
+        $identifier = (new GenericSnowflakeFactory($this->node, $this->epochOffset))->create();
+
+        $event->state->register($this->field, $identifier);
+    }
+}

src/Listener/SnowflakeInstagram.php

@@ -0,0 +1,30 @@
+<?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;
+use Ramsey\Identifier\Snowflake\InstagramSnowflakeFactory;
+
+final class SnowflakeInstagram
+{
+    public function __construct(
+        private string $field = 'snowflake',
+        private int $shardId = 0,
+        private bool $nullable = false,
+    ) {}
+
+    #[Listen(OnCreate::class)]
+    public function __invoke(OnCreate $event): void
+    {
+        if ($this->nullable || isset($event->state->getData()[$this->field])) {
+            return;
+        }
+
+        $identifier = (new InstagramSnowflakeFactory($this->shardId))->create();
+
+        $event->state->register($this->field, $identifier);
+    }
+}

src/Listener/SnowflakeMastodon.php

@@ -0,0 +1,33 @@
+<?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;
+use Ramsey\Identifier\Snowflake\MastodonSnowflakeFactory;
+
+final class SnowflakeMastodon
+{
+    /**
+     * @param non-empty-string|null $tableName
+     */
+    public function __construct(
+        private string $field = 'snowflake',
+        private ?string $tableName = null,
+        private bool $nullable = false,
+    ) {}
+
+    #[Listen(OnCreate::class)]
+    public function __invoke(OnCreate $event): void
+    {
+        if ($this->nullable || isset($event->state->getData()[$this->field])) {
+            return;
+        }
+
+        $identifier = (new MastodonSnowflakeFactory($this->tableName))->create();
+
+        $event->state->register($this->field, $identifier);
+    }
+}

src/Listener/SnowflakeTwitter.php

@@ -0,0 +1,30 @@
+<?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;
+use Ramsey\Identifier\Snowflake\TwitterSnowflakeFactory;
+
+final class SnowflakeTwitter
+{
+    public function __construct(
+        private string $field = 'snowflake',
+        private int $machineId = 0,
+        private bool $nullable = false,
+    ) {}
+
+    #[Listen(OnCreate::class)]
+    public function __invoke(OnCreate $event): void
+    {
+        if ($this->nullable || isset($event->state->getData()[$this->field])) {
+            return;
+        }
+
+        $identifier = (new TwitterSnowflakeFactory($this->machineId))->create();
+
+        $event->state->register($this->field, $identifier);
+    }
+}

src/Snowflake.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\ORM\Entity\Behavior\Identifier;
+
+use Cycle\ORM\Entity\Behavior\Schema\BaseModifier;
+use Cycle\ORM\Entity\Behavior\Schema\RegistryModifier;
+use Cycle\ORM\Schema\GeneratedField;
+use Cycle\Schema\Registry;
+use Ramsey\Identifier\SnowflakeFactory;
+
+abstract class Snowflake extends BaseModifier
+{
+    protected ?string $column = null;
+    protected string $field;
+    protected bool $nullable = false;
+
+    #[\Override]
+    public function compute(Registry $registry): void
+    {
+        $modifier = new RegistryModifier($registry, $this->role);
+        $this->column = $modifier->findColumnName($this->field, $this->column);
+        if (\is_string($this->column) && $this->column !== '') {
+            $modifier->addSnowflakeColumn(
+                $this->column,
+                $this->field,
+                $this->nullable ? null : GeneratedField::BEFORE_INSERT,
+            )->nullable($this->nullable);
+
+            $factory = $this->snowflakeFactory();
+
+            $modifier->setTypecast(
+                $registry->getEntity($this->role)->getFields()->get($this->field),
+                [$factory, 'createFromInteger'],
+            );
+        }
+    }
+
+    #[\Override]
+    public function render(Registry $registry): void
+    {
+        $modifier = new RegistryModifier($registry, $this->role);
+        /** @var non-empty-string column */
+        $this->column = $modifier->findColumnName($this->field, $this->column) ?? $this->field;
+
+        $modifier->addSnowflakeColumn(
+            $this->column,
+            $this->field,
+            $this->nullable ? null : GeneratedField::BEFORE_INSERT,
+        )->nullable($this->nullable);
+
+        $factory = $this->snowflakeFactory();
+
+        $modifier->setTypecast(
+            $registry->getEntity($this->role)->getFields()->get($this->field),
+            [$factory, 'createFromInteger'],
+        );
+    }
+
+    abstract protected function snowflakeFactory(): SnowflakeFactory;
+}