From 4e2fc803c62ae91b01864c7336d9abb9d827981a Mon Sep 17 00:00:00 2001 From: Ben Ramsey Date: Sat, 13 Aug 2022 10:21:59 -0500 Subject: [PATCH] feat: introduce TimeBasedUuidFactoryInterface --- CHANGELOG.md | 5 ++- src/DeprecatedUuidFactoryInterface.php | 6 ++-- src/TimeBasedUuidFactoryInterface.php | 48 ++++++++++++++++++++++++++ src/Uuid.php | 6 ++-- src/UuidFactory.php | 2 ++ src/UuidFactoryInterface.php | 2 ++ src/UuidInterface.php | 16 ++++----- tests/UuidFactoryTest.php | 2 ++ 8 files changed, 72 insertions(+), 15 deletions(-) create mode 100644 src/TimeBasedUuidFactoryInterface.php diff --git a/CHANGELOG.md b/CHANGELOG.md index 96e6e88..e269e1c 100644 --- a/CHANGELOG.md +++ b/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: diff --git a/src/DeprecatedUuidFactoryInterface.php b/src/DeprecatedUuidFactoryInterface.php index 0b3d6a3..c450ff9 100644 --- a/src/DeprecatedUuidFactoryInterface.php +++ b/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 diff --git a/src/TimeBasedUuidFactoryInterface.php b/src/TimeBasedUuidFactoryInterface.php new file mode 100644 index 0000000..9fb5ad7 --- /dev/null +++ b/src/TimeBasedUuidFactoryInterface.php @@ -0,0 +1,48 @@ + + * @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; +} diff --git a/src/Uuid.php b/src/Uuid.php index 074278e..770f31d 100644 --- a/src/Uuid.php +++ b/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 diff --git a/src/UuidFactory.php b/src/UuidFactory.php index 98ade95..221b475 100644 --- a/src/UuidFactory.php +++ b/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 { diff --git a/src/UuidFactoryInterface.php b/src/UuidFactoryInterface.php index 9f08c29..0fd9708 100644 --- a/src/UuidFactoryInterface.php +++ b/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 { diff --git a/src/UuidInterface.php b/src/UuidInterface.php index 105cd70..8fb1b6b 100644 --- a/src/UuidInterface.php +++ b/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; } diff --git a/tests/UuidFactoryTest.php b/tests/UuidFactoryTest.php index 44422f2..8a0a06d 100644 --- a/tests/UuidFactoryTest.php +++ b/tests/UuidFactoryTest.php @@ -139,6 +139,8 @@ class UuidFactoryTest extends TestCase } /** + * @param int<0, 16383>|null $clockSeq + * * @dataProvider provideDateTime */ public function testFromDateTime(