Refactor other Snowflakes

Author: roxblnfk

README.md

@@ -18,7 +18,8 @@ composer require cycle/entity-behavior-identifier
 
 ## Snowflake Examples
 
-**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`.
+### 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.
 
 ```php
 use Cycle\Annotated\Annotation\Column;
@@ -71,7 +72,8 @@ class User
 }
 ```
 
-**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`.
+### 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;
@@ -88,7 +90,8 @@ class User
 }
 ```
 
-**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`.
+### 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;

src/Defaults/SnowflakeGeneric.php

@@ -4,29 +4,63 @@
 
 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;
 use Ramsey\Identifier\Snowflake\Epoch;
 use Ramsey\Identifier\Snowflake\GenericSnowflakeFactory;
 
-final class SnowflakeGeneric
+/**
+ * Generates generic Snowflake identifiers for entities.
+ * You can set default node and epoch offset using the {@see setDefaults()} method.
+ */
+final class SnowflakeGeneric extends \Cycle\ORM\Entity\Behavior\Identifier\Listener\Snowflake
 {
+    /** @var int<0, 1023> */
+    private static int $node = 0;
+
+    /** @var Epoch|int */
+    private static Epoch|int $epochOffset = 0;
+
+    private GenericSnowflakeFactory $factory;
+
+    /**
+     * @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
+     * @param int<0, 1023>|null $node A node identifier to use when creating Snowflakes
+     * @param Epoch|int|null $epochOffset The offset from the Unix Epoch in milliseconds
+     */
     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
+        string $field,
+        bool $nullable = false,
+        ?int $node = null,
+        Epoch|int|null $epochOffset = null,
+    ) {
+        $node ??= self::$node;
+        $epochOffset ??= self::$epochOffset;
+        $this->factory = new GenericSnowflakeFactory($node, $epochOffset);
+        parent::__construct($field, $nullable);
+    }
+
+    /**
+     * Set default node and epoch offset for Snowflake generation.
+     *
+     * @param null|int<0, 1023> $node The node ID to set. Null to use the default (0).
+     * @param Epoch|int|null $epochOffset The epoch offset to set. Null to use the default (0).
+     */
+    public static function setDefaults(?int $node, Epoch|int|null $epochOffset): void
     {
-        if ($this->nullable || isset($event->state->getData()[$this->field])) {
-            return;
+        if ($node !== null && ($node < 0 || $node > 1023)) {
+            throw new \InvalidArgumentException('Node ID must be between 0 and 1023.');
         }
 
-        $identifier = (new GenericSnowflakeFactory($this->node, $this->epochOffset))->create();
+        self::$node = (int) $node;
+        if ($epochOffset !== null) {
+            self::$epochOffset = $epochOffset;
+        }
+    }
 
-        $event->state->register($this->field, $identifier);
+    #[\Override]
+    protected function createValue(): Snowflake
+    {
+        return $this->factory->create();
     }
 }

src/Defaults/SnowflakeMastodon.php

@@ -4,30 +4,48 @@
 
 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\MastodonSnowflake;
 use Ramsey\Identifier\Snowflake\MastodonSnowflakeFactory;
 
-final class SnowflakeMastodon
+/**
+ * Generates Mastodon Snowflake identifiers for entities.
+ * You can set default table name using the {@see setDefaults()} method.
+ */
+final class SnowflakeMastodon extends Snowflake
 {
+    /** @var non-empty-string|null */
+    private static ?string $tableName = null;
+
+    private MastodonSnowflakeFactory $factory;
+
     /**
-     * @param non-empty-string|null $tableName
+     * @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
+     * @param non-empty-string|null $tableName Database table name ensuring different tables derive separate sequence bases
      */
     public function __construct(
-        private string $field = 'snowflake',
-        private ?string $tableName = null,
-        private bool $nullable = false,
-    ) {}
+        string $field,
+        bool $nullable = false,
+        ?string $tableName = null,
+    ) {
+        $tableName ??= self::$tableName;
+        $this->factory = new MastodonSnowflakeFactory($tableName);
+        parent::__construct($field, $nullable);
+    }
 
-    #[Listen(OnCreate::class)]
-    public function __invoke(OnCreate $event): void
+    /**
+     * Set default table name for Snowflake generation.
+     *
+     * @param non-empty-string|null $tableName The table name to set. Null to use the default (null).
+     */
+    public static function setDefaults(?string $tableName): void
     {
-        if ($this->nullable || isset($event->state->getData()[$this->field])) {
-            return;
-        }
-
-        $identifier = (new MastodonSnowflakeFactory($this->tableName))->create();
+        self::$tableName = $tableName;
+    }
 
-        $event->state->register($this->field, $identifier);
+    #[\Override]
+    protected function createValue(): MastodonSnowflake
+    {
+        return $this->factory->create();
     }
 }

src/Defaults/SnowflakeTwitter.php

@@ -4,27 +4,52 @@
 
 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\TwitterSnowflake;
 use Ramsey\Identifier\Snowflake\TwitterSnowflakeFactory;
 
-final class SnowflakeTwitter
+/**
+ * Generates Twitter Snowflake identifiers for entities.
+ * You can set default machine ID using the {@see setDefaults()} method.
+ */
+final class SnowflakeTwitter extends Snowflake
 {
+    /** @var int<0, 1023> */
+    private static int $machineId = 0;
+
+    private TwitterSnowflakeFactory $factory;
+
+    /**
+     * @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
+     * @param int<0, 1023>|null $machineId A machine identifier to use when creating Snowflakes
+     */
     public function __construct(
-        private string $field = 'snowflake',
-        private int $machineId = 0,
-        private bool $nullable = false,
-    ) {}
+        string $field,
+        bool $nullable = false,
+        ?int $machineId = null,
+    ) {
+        $machineId ??= self::$machineId;
+        $this->factory = new TwitterSnowflakeFactory($machineId);
+        parent::__construct($field, $nullable);
+    }
 
-    #[Listen(OnCreate::class)]
-    public function __invoke(OnCreate $event): void
+    /**
+     * Set default machine ID for Snowflake generation.
+     *
+     * @param null|int<0, 1023> $machineId The machine ID to set. Null to use the default (0).
+     */
+    public static function setDefaults(?int $machineId): void
     {
-        if ($this->nullable || isset($event->state->getData()[$this->field])) {
-            return;
+        if ($machineId !== null && ($machineId < 0 || $machineId > 1023)) {
+            throw new \InvalidArgumentException('Machine ID must be between 0 and 1023.');
         }
 
-        $identifier = (new TwitterSnowflakeFactory($this->machineId))->create();
+        self::$machineId = (int) $machineId;
+    }
 
-        $event->state->register($this->field, $identifier);
+    #[\Override]
+    protected function createValue(): TwitterSnowflake
+    {
+        return $this->factory->create();
     }
 }

src/Listener/SnowflakeGeneric.php

@@ -5,10 +5,8 @@
 namespace Cycle\ORM\Entity\Behavior\Identifier;
 
 use Cycle\ORM\Entity\Behavior\Identifier\Snowflake as BaseSnowflake;
-use Cycle\ORM\Entity\Behavior\Identifier\Defaults\SnowflakeGeneric as Defaults;
 use Cycle\ORM\Entity\Behavior\Identifier\Listener\SnowflakeGeneric as Listener;
 use Doctrine\Common\Annotations\Annotation\NamedArgumentConstructor;
-use JetBrains\PhpStorm\ArrayShape;
 use Ramsey\Identifier\Snowflake\Epoch;
 use Ramsey\Identifier\Snowflake\GenericSnowflakeFactory;
 use Ramsey\Identifier\SnowflakeFactory;
@@ -24,30 +22,25 @@
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE), NamedArgumentConstructor]
 final class SnowflakeGeneric extends BaseSnowflake
 {
-    private int $node;
-    private Epoch|int $epochOffset;
-
     /**
      * @param non-empty-string $field Snowflake property name
-     * @param string|null $column Snowflake column name
-     * @param int|null $node A node identifier to use when creating Snowflakes
+     * @param non-empty-string|null $column Snowflake column name
+     * @param int<0, 1023>|null $node A node identifier to use when creating Snowflakes
      * @param Epoch|int|null $epochOffset The offset from the Unix Epoch in milliseconds
      * @param bool $nullable Indicates whether to generate a new Snowflake or not
      *
      * @see \Ramsey\Identifier\Snowflake\GenericSnowflakeFactory::create()
      */
     public function __construct(
-        string $field = 'snowflake',
+        string $field,
         ?string $column = null,
-        ?int $node = null,
-        Epoch|int|null $epochOffset = null,
+        private readonly ?int $node = null,
+        private readonly Epoch|int|null $epochOffset = null,
         bool $nullable = false,
     ) {
         $this->field = $field;
         $this->column = $column;
         $this->nullable = $nullable;
-        $this->node = $node === null ? Defaults::getNode() : $node;
-        $this->epochOffset = $epochOffset === null ? Defaults::getEpochOffset() : $epochOffset;
     }
 
     #[\Override]
@@ -56,12 +49,14 @@ protected function getListenerClass(): string
         return Listener::class;
     }
 
-    #[ArrayShape([
-        'field' => 'string',
-        'node' => 'Epoch|int',
-        'epochOffset' => 'int',
-        'nullable' => 'bool',
-    ])]
+    /**
+     * @return array{
+     *     field: non-empty-string,
+     *     node: null|int<0, 1023>,
+     *     epochOffset: Epoch|int|null,
+     *     nullable: bool
+     * }
+     */
     #[\Override]
     protected function getListenerArgs(): array
     {