feat: introduce TimeBasedUuidFactoryInterface

CHANGELOG.md

@@ -11,13 +11,15 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 * Introduce `Ramsey\Uuid\TimeBasedUuidInterface` to represent any UUID based on
   a date/time value.
+* Introduce `Ramsey\Uuid\TimeBasedUuidFactoryInterface` to represent any factory
+  for creating UUIDs based on a date/time value.
 * Introduce `Ramsey\Uuid\Variant` enum to represent the variant field.
 * Introduce `Ramsey\Uuid\Rfc4122\Version` enum to represent the version field.
 * Add new static method `Ramsey\Uuid\BinaryUtils::applyVersionAndVariant()`.
 
 ### Changed
 
-* Remove the following deprecated classes:
+* Remove the following deprecated classes and interfaces:
   * `Ramsey\Uuid\Builder\BuilderCollection`
   * `Ramsey\Uuid\Builder\DefaultUuidBuilder`
   * `Ramsey\Uuid\Builder\DegradedUuidBuilder`
@@ -26,6 +28,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
   * `Ramsey\Uuid\Converter\Time\BigNumberTimeConverter`
   * `Ramsey\Uuid\Converter\Time\DegradedTimeConverter`
   * `Ramsey\Uuid\DegradedUuid`
+  * `Ramsey\Uuid\DeprecatedUuidFactoryInterface`
   * `Ramsey\Uuid\Generator\RandomLibAdapter`
   * `Ramsey\Uuid\Provider\Node\NodeProviderCollection`
 * Remove the following deprecated methods from Uuid classes:

src/DeprecatedUuidFactoryInterface.php

@@ -37,9 +37,9 @@ interface DeprecatedUuidFactoryInterface
      * @param DateTimeInterface $dateTime The date and time
      * @param Hexadecimal|null $node A 48-bit number representing the hardware
      *     address
-     * @param int|null $clockSeq A 14-bit number used to help avoid duplicates
-     *     that could arise when the clock is set backwards in time or if the
-     *     node ID changes
+     * @param int<0, 16383>|null $clockSeq A 14-bit number used to help avoid
+     *     duplicates that could arise when the clock is set backwards in time
+     *     or if the node ID changes
      *
      * @return UuidInterface A UuidInterface instance that represents a
      *     version 1 UUID created from a DateTimeInterface instance

src/TimeBasedUuidFactoryInterface.php

@@ -0,0 +1,48 @@
+<?php
+
+/**
+ * This file is part of the ramsey/uuid library
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @copyright Copyright (c) Ben Ramsey <ben@benramsey.com>
+ * @license http://opensource.org/licenses/MIT MIT
+ */
+
+declare(strict_types=1);
+
+namespace Ramsey\Uuid;
+
+use DateTimeInterface;
+use Ramsey\Uuid\Type\Hexadecimal;
+
+/**
+ * TimeBasedUuidFactoryInterface defines common functionality all factories for
+ * time-based UUIDs must implement
+ *
+ * @psalm-immutable
+ */
+interface TimeBasedUuidFactoryInterface extends UuidFactoryInterface
+{
+    /**
+     * Creates a UUID from a DateTimeInterface instance
+     *
+     * @param DateTimeInterface $dateTime The date and time
+     * @param Hexadecimal|null $node A 48-bit number representing the hardware
+     *     address
+     * @param int<0, 16383>|null $clockSeq A 14-bit number used to help avoid
+     *     duplicates that could arise when the clock is set backwards in time
+     *     or if the node ID changes
+     *
+     * @return UuidInterface A UuidInterface instance that represents a
+     *     UUID created from a DateTimeInterface instance
+     *
+     * @psalm-pure
+     */
+    public function fromDateTime(
+        DateTimeInterface $dateTime,
+        ?Hexadecimal $node = null,
+        ?int $clockSeq = null
+    ): UuidInterface;
+}

src/Uuid.php

@@ -387,9 +387,9 @@ class Uuid implements Rfc4122UuidInterface
      * @param DateTimeInterface $dateTime The date and time
      * @param Hexadecimal|null $node A 48-bit number representing the hardware
      *     address
-     * @param int|null $clockSeq A 14-bit number used to help avoid duplicates
-     *     that could arise when the clock is set backwards in time or if the
-     *     node ID changes
+     * @param int<0, 16383>|null $clockSeq A 14-bit number used to help avoid
+     *     duplicates that could arise when the clock is set backwards in time
+     *     or if the node ID changes
      *
      * @return UuidInterface A UuidInterface instance that represents a
      *     version 1 UUID created from a DateTimeInterface instance

src/UuidFactory.php

@@ -44,6 +44,8 @@ use const STR_PAD_LEFT;
 /**
  * @deprecated UuidFactory will go away in ramsey/uuid version 5. Use dedicated
  *     factories for subtypes instead.
+ *
+ * @psalm-suppress MissingImmutableAnnotation
  */
 class UuidFactory implements UuidFactoryInterface
 {

src/UuidFactoryInterface.php

@@ -17,6 +17,8 @@ namespace Ramsey\Uuid;
 /**
  * UuidFactoryInterface defines common functionality all `UuidFactory` instances
  * must implement
+ *
+ * @psalm-immutable
  */
 interface UuidFactoryInterface extends DeprecatedUuidFactoryInterface
 {

src/UuidInterface.php

@@ -32,6 +32,13 @@ interface UuidInterface extends JsonSerializable
      */
     public function __serialize(): array;
 
+    /**
+     * Casts the UUID to the string standard representation
+     *
+     * @psalm-return non-empty-string
+     */
+    public function __toString(): string;
+
     /**
      * @param mixed[] $data
      */
@@ -58,7 +65,7 @@ interface UuidInterface extends JsonSerializable
      * Returns true if the UUID is equal to the provided object
      *
      * The result is true if and only if the argument is not null, is a UUID
-     * object, has the same variant, and contains the same value, bit for bit,
+     * object, has the same variant, and contains the same value, bit-for-bit,
      * as the UUID.
      *
      * @param object|null $other An object to test for equality with this UUID
@@ -103,11 +110,4 @@ interface UuidInterface extends JsonSerializable
      * @psalm-return non-empty-string
      */
     public function toString(): string;
-
-    /**
-     * Casts the UUID to the string standard representation
-     *
-     * @psalm-return non-empty-string
-     */
-    public function __toString(): string;
 }

tests/UuidFactoryTest.php

@@ -139,6 +139,8 @@ class UuidFactoryTest extends TestCase
     }
 
     /**
+     * @param int<0, 16383>|null $clockSeq
+     *
      * @dataProvider provideDateTime
      */
     public function testFromDateTime(