Refactor UUID listeners

Author: roxblnfk

README.md

@@ -129,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. Default values for `node` and `clockSeq` can be defined globally via class `Cycle\ORM\Entity\Behavior\Identifier\Defaults\Uuid1`.
+### 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;
@@ -146,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. Default values for `localDomain`, `localIdentifier`, `node` and `clockSeq` can be defined globally via class `Cycle\ORM\Entity\Behavior\Identifier\Defaults\Uuid2`.
+### 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;
@@ -222,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). Default values for `node` and `clockSeq` can be defined globally via class `Cycle\ORM\Entity\Behavior\Identifier\Defaults\Uuid6`.
+### 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;

src/Defaults/Uuid1.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/Defaults/Uuid2.php

@@ -14,10 +14,10 @@
 final class SnowflakeDiscord extends Snowflake
 {
     /** @var int<0, 281474976710655> */
-    private static int $workerId = 0;
+    private static int $defaultWorkerId = 0;
 
     /** @var null|int<0, 281474976710655> */
-    private static ?int $processId = null;
+    private static ?int $defaultProcessId = null;
 
     private DiscordSnowflakeFactory $factory;
 
@@ -33,7 +33,7 @@ public function __construct(
         ?int $workerId = null,
         ?int $processId = null,
     ) {
-        $workerId ??= self::$workerId;
+        $workerId ??= self::$defaultWorkerId;
         $processId ??= $this->getProcessId();
         $this->factory = new DiscordSnowflakeFactory($workerId, $processId);
         parent::__construct($field, $nullable);
@@ -54,8 +54,8 @@ public static function setDefaults(?int $workerId, ?int $processId): void
             throw new \InvalidArgumentException('Process ID must be between 0 and 281474976710655.');
         }
 
-        self::$workerId = (int) $workerId;
-        self::$processId = $processId;
+        self::$defaultWorkerId = (int) $workerId;
+        self::$defaultProcessId = $processId;
     }
 
     #[\Override]
@@ -71,6 +71,6 @@ protected function createValue(): DiscordSnowflake
      */
     private function getProcessId(): int
     {
-        return self::$processId ??= \getmypid();
+        return self::$defaultProcessId ??= \getmypid();
     }
 }

src/Defaults/Uuid6.php

@@ -17,7 +17,6 @@ final class SnowflakeGeneric extends \Cycle\ORM\Entity\Behavior\Identifier\Liste
     /** @var int<0, 1023> */
     private static int $node = 0;
 
-    /** @var Epoch|int */
     private static Epoch|int $epochOffset = 0;
 
     private GenericSnowflakeFactory $factory;

src/Listener/BaseUuid.php

@@ -4,34 +4,53 @@
 
 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\Uuid\UuidFactory;
+use Ramsey\Identifier\Uuid\UuidV1Factory;
 
-final class Uuid1
+/**
+ * Generates UUIDv1 identifiers for entities.
+ * You can set default node and clock sequence using the {@see setDefaults()} method.
+ */
+final class Uuid1 extends BaseUuid
 {
+    /** @var int<0, 281474976710655>|non-empty-string|null */
+    private static int|string|null $defaultNode = null;
+
+    private static ?int $defaultClockSeq = null;
+    private UuidV1Factory $factory;
+
     /**
-     * @param int<0, 281474976710655>|non-empty-string|null $node
+     * @param non-empty-string $field The name of the field to store the UUID
+     * @param bool $nullable Indicates whether the UUID can be null
+     * @param int<0, 281474976710655>|non-empty-string|null $node A 48-bit integer or hexadecimal string representing the hardware address
+     * @param int|null $clockSeq A number used to help avoid duplicates that could arise when the clock is set backwards in time
      */
     public function __construct(
-        private string $field = 'uuid',
-        private int|string|null $node = null,
-        private ?int $clockSeq = null,
-        private bool $nullable = false,
-    ) {}
-
-    #[Listen(OnCreate::class)]
-    public function __invoke(OnCreate $event): void
-    {
-        if ($this->nullable || isset($event->state->getData()[$this->field])) {
-            return;
-        }
+        string $field,
+        bool $nullable = false,
+        private readonly int|string|null $node = null,
+        private readonly ?int $clockSeq = null,
+    ) {
+        $this->factory = new UuidV1Factory();
+        parent::__construct($field, $nullable);
+    }
 
-        $identifier = (new UuidFactory())->v1(
-            $this->node,
-            $this->clockSeq,
-        );
+    /**
+     * Set default node and clock sequence for UUIDv1 generation.
+     *
+     * @param int<0, 281474976710655>|non-empty-string|null $node The node to set
+     * @param int|null $clockSeq The clock sequence to set
+     */
+    public static function setDefaults(int|string|null $node, ?int $clockSeq): void
+    {
+        self::$defaultNode = $node;
+        self::$defaultClockSeq = $clockSeq;
+    }
 
-        $event->state->register($this->field, $identifier);
+    #[\Override]
+    protected function createValue(): \Ramsey\Identifier\Uuid
+    {
+        $node = $this->node ?? self::$defaultNode;
+        $clockSeq = $this->clockSeq ?? self::$defaultClockSeq;
+        return $this->factory->create($node, $clockSeq);
     }
 }