diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a7cf08..79fdcbf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,12 +10,25 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Added +* Add `ValidatorInterface::getPattern()` to return the regular expression + pattern used by the validator. +* Add `v6()` helper function for version 6 UUIDs. + ### Changed +* Set the pattern constants on validators as `private`. Use the `getPattern()` + method instead. +* Change the `$node` parameter for `UuidFactoryInterface::uuid6()` to accept + `null` or `Type\Hexadecimal`. + ### Deprecated ### Removed +* Remove `currentTime()` method from `Provider\Time\FixedTimeProvider` and + `Provider\Time\SystemTimeProvider`; it had previously been removed from + `Provider\TimeProviderInterface`. + ### Fixed ### Security diff --git a/src/Uuid.php b/src/Uuid.php index 99cb9a1..a0d1dd1 100644 --- a/src/Uuid.php +++ b/src/Uuid.php @@ -545,8 +545,8 @@ class Uuid implements UuidInterface * Returns a version 6 (ordered-time) UUID from a host ID, sequence number, * and the current time * - * @param int|string $node A 48-bit number representing the hardware address; - * this number may be represented as an integer or a hexadecimal string + * @param Hexadecimal|null $node A 48-bit number representing the hardware + * address * @param int $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 @@ -554,8 +554,10 @@ class Uuid implements UuidInterface * @return UuidInterface A UuidInterface instance that represents a * version 6 UUID */ - public static function uuid6($node = null, ?int $clockSeq = null): UuidInterface - { + public static function uuid6( + ?Hexadecimal $node = null, + ?int $clockSeq = null + ): UuidInterface { return self::getFactory()->uuid6($node, $clockSeq); } } diff --git a/src/UuidFactory.php b/src/UuidFactory.php index acb52f9..afa17d4 100644 --- a/src/UuidFactory.php +++ b/src/UuidFactory.php @@ -353,12 +353,10 @@ class UuidFactory implements UuidFactoryInterface return $this->uuidFromNsAndName($ns, $name, 5, 'sha1'); } - /** - * @inheritDoc - */ - public function uuid6($node = null, ?int $clockSeq = null): UuidInterface + public function uuid6(?Hexadecimal $node = null, ?int $clockSeq = null): UuidInterface { - $bytes = $this->timeGenerator->generate($node, $clockSeq); + $nodeHex = $node ? $node->toString() : null; + $bytes = $this->timeGenerator->generate($nodeHex, $clockSeq); // Rearrange the bytes, according to the UUID version 6 specification. $v6 = $bytes[6] . $bytes[7] . $bytes[4] . $bytes[5] diff --git a/src/UuidFactoryInterface.php b/src/UuidFactoryInterface.php index 03505e1..ec2ddb8 100644 --- a/src/UuidFactoryInterface.php +++ b/src/UuidFactoryInterface.php @@ -109,8 +109,8 @@ interface UuidFactoryInterface * Returns a version 6 (ordered-time) UUID from a host ID, sequence number, * and the current time * - * @param int|string $node A 48-bit number representing the hardware address; - * this number may be represented as an integer or a hexadecimal string + * @param Hexadecimal|null $node A 48-bit number representing the hardware + * address * @param int $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 @@ -118,7 +118,7 @@ interface UuidFactoryInterface * @return UuidInterface A UuidInterface instance that represents a * version 6 UUID */ - public function uuid6($node = null, ?int $clockSeq = null): UuidInterface; + public function uuid6(?Hexadecimal $node = null, ?int $clockSeq = null): UuidInterface; /** * Creates a UUID from a byte string diff --git a/src/functions.php b/src/functions.php index 2eb8f42..b148447 100644 --- a/src/functions.php +++ b/src/functions.php @@ -27,6 +27,8 @@ use Ramsey\Uuid\Type\Integer as IntegerObject; * @param int $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 string Version 1 UUID as a string */ function v1($node = null, ?int $clockSeq = null): string { @@ -48,6 +50,8 @@ function v1($node = null, ?int $clockSeq = null): string * @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 + * + * @return string Version 2 UUID as a string */ function v2( int $localDomain, @@ -63,6 +67,8 @@ function v2( * namespace ID and a name * * @param string|UuidInterface $ns The namespace (must be a valid UUID) + * + * @return string Version 3 UUID as a string */ function v3($ns, string $name): string { @@ -71,6 +77,8 @@ function v3($ns, string $name): string /** * Returns a version 4 (random) UUID + * + * @return string Version 4 UUID as a string */ function v4(): string { @@ -82,8 +90,27 @@ function v4(): string * namespace ID and a name * * @param string|UuidInterface $ns The namespace (must be a valid UUID) + * + * @return string Version 5 UUID as a string */ function v5($ns, string $name): string { return Uuid::uuid5($ns, $name)->toString(); } + +/** + * Returns a version 6 (ordered-time) UUID from a host ID, sequence number, + * and the current time + * + * @param Hexadecimal|null $node A 48-bit number representing the hardware + * address + * @param int $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 string Version 6 UUID as a string + */ +function v6(?Hexadecimal $node = null, ?int $clockSeq = null): string +{ + return Uuid::uuid6($node, $clockSeq)->toString(); +} diff --git a/tests/FunctionsTest.php b/tests/FunctionsTest.php index 26d84c1..399d533 100644 --- a/tests/FunctionsTest.php +++ b/tests/FunctionsTest.php @@ -14,6 +14,7 @@ use function Ramsey\Uuid\v2; use function Ramsey\Uuid\v3; use function Ramsey\Uuid\v4; use function Ramsey\Uuid\v5; +use function Ramsey\Uuid\v6; class FunctionsTest extends TestCase { @@ -66,4 +67,18 @@ class FunctionsTest extends TestCase $this->assertIsString($v5); $this->assertSame(Uuid::UUID_TYPE_HASH_SHA1, Uuid::fromString($v5)->getVersion()); } + + public function testV6ReturnsVersion6UuidString(): void + { + $v6 = v6( + new Hexadecimal('aabbccdd0011'), + 1234 + ); + + /** @var FieldsInterface $fields */ + $fields = Uuid::fromString($v6)->getFields(); + + $this->assertIsString($v6); + $this->assertSame(Uuid::UUID_TYPE_PEABODY, $fields->getVersion()); + } } diff --git a/tests/UuidTest.php b/tests/UuidTest.php index 80d3e0c..2a6d3b2 100644 --- a/tests/UuidTest.php +++ b/tests/UuidTest.php @@ -553,7 +553,7 @@ class UuidTest extends TestCase public function testUuid6WithNodeAndClockSequence(): void { - $uuid = Uuid::uuid6('0800200c9a66', 0x1669); + $uuid = Uuid::uuid6(new Hexadecimal('0800200c9a66'), 0x1669); $this->assertInstanceOf(UuidV6::class, $uuid); $this->assertInstanceOf(DateTimeInterface::class, $uuid->getDateTime()); $this->assertSame(2, $uuid->getVariant()); @@ -565,7 +565,7 @@ class UuidTest extends TestCase public function testUuid6WithHexadecimalNode(): void { - $uuid = Uuid::uuid6('7160355e'); + $uuid = Uuid::uuid6(new Hexadecimal('7160355e')); $this->assertInstanceOf(UuidV6::class, $uuid); $this->assertInstanceOf(DateTimeInterface::class, $uuid->getDateTime()); @@ -576,7 +576,7 @@ class UuidTest extends TestCase public function testUuid6WithMixedCaseHexadecimalNode(): void { - $uuid = Uuid::uuid6('71B0aD5e'); + $uuid = Uuid::uuid6(new Hexadecimal('71B0aD5e')); $this->assertInstanceOf(Uuid::class, $uuid); $this->assertInstanceOf(DateTimeInterface::class, $uuid->getDateTime()); @@ -590,15 +590,7 @@ class UuidTest extends TestCase $this->expectException(InvalidArgumentException::class); $this->expectExceptionMessage('Invalid node value'); - Uuid::uuid6('9223372036854775808'); - } - - public function testUuid6WithNonHexadecimalNode(): void - { - $this->expectException(InvalidArgumentException::class); - $this->expectExceptionMessage('Invalid node value'); - - Uuid::uuid6('db77e160355g'); + Uuid::uuid6(new Hexadecimal('9223372036854775808')); } public function testUuid6WithNon48bitNumber(): void @@ -606,7 +598,7 @@ class UuidTest extends TestCase $this->expectException(InvalidArgumentException::class); $this->expectExceptionMessage('Invalid node value'); - Uuid::uuid6('db77e160355ef'); + Uuid::uuid6(new Hexadecimal('db77e160355ef')); } public function testUuid6WithRandomNode(): void