diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c62a65..b512743 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -89,6 +89,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. of `mixed`. This is a string representation of a 128-bit integer. You may then use a math library of your choice (bcmath, gmp, etc.) to operate on the string integer. +* Change the second required parameter of `Builder\UuidBuilderInterface::build()` + from `array $fields` to `string $bytes`. Rather than accepting an array of + hexadecimal strings as UUID fields, the `build()` method now expects a byte + string. * Change methods in converter interfaces to accept and return string values instead of `mixed`; this simplifies the interface and makes it consistent: * `NumberConverterInterface::fromHex(string $hex): string` diff --git a/src/Builder/DegradedUuidBuilder.php b/src/Builder/DegradedUuidBuilder.php index 6bf0884..18af18b 100644 --- a/src/Builder/DegradedUuidBuilder.php +++ b/src/Builder/DegradedUuidBuilder.php @@ -58,16 +58,14 @@ class DegradedUuidBuilder implements UuidBuilderInterface * Builds and returns a DegradedUuid * * @param CodecInterface $codec The codec to use for building this DegradedUuid instance - * @param string[] $fields An array of fields from which to construct a DegradedUuid instance + * @param string $bytes The byte string from which to construct a UUID * * @return DegradedUuid The DegradedUuidBuild returns an instance of Ramsey\Uuid\DegradedUuid */ - public function build(CodecInterface $codec, array $fields): UuidInterface + public function build(CodecInterface $codec, string $bytes): UuidInterface { - $fields = new Rfc4122Fields((string) hex2bin(implode('', $fields))); - return new DegradedUuid( - $fields, + new Rfc4122Fields($bytes), $this->numberConverter, $codec, $this->timeConverter diff --git a/src/Builder/FallbackBuilder.php b/src/Builder/FallbackBuilder.php index 0b1cc59..7dca340 100644 --- a/src/Builder/FallbackBuilder.php +++ b/src/Builder/FallbackBuilder.php @@ -45,18 +45,17 @@ class FallbackBuilder implements UuidBuilderInterface * succeeds * * @param CodecInterface $codec The codec to use for building this instance - * @param string[] $fields An array of fields from which to construct an instance; - * see {@see \Ramsey\Uuid\UuidInterface::getFieldsHex()} for array structure. + * @param string $bytes The byte string from which to construct a UUID * * @return UuidInterface an instance of a UUID object */ - public function build(CodecInterface $codec, array $fields): UuidInterface + public function build(CodecInterface $codec, string $bytes): UuidInterface { $lastBuilderException = null; foreach ($this->builders as $builder) { try { - return $builder->build($codec, $fields); + return $builder->build($codec, $bytes); } catch (UnableToBuildUuidException $exception) { $lastBuilderException = $exception; diff --git a/src/Builder/UuidBuilderInterface.php b/src/Builder/UuidBuilderInterface.php index 2aff20a..f9611cd 100644 --- a/src/Builder/UuidBuilderInterface.php +++ b/src/Builder/UuidBuilderInterface.php @@ -28,10 +28,10 @@ interface UuidBuilderInterface * Builds and returns a UuidInterface * * @param CodecInterface $codec The codec to use for building this UuidInterface instance - * @param string[] $fields An array of fields from which to construct a UuidInterface instance + * @param string $bytes The byte string from which to construct a UUID * * @return UuidInterface Implementations may choose to return more specific * instances of UUIDs that implement UuidInterface */ - public function build(CodecInterface $codec, array $fields): UuidInterface; + public function build(CodecInterface $codec, string $bytes): UuidInterface; } diff --git a/src/Codec/StringCodec.php b/src/Codec/StringCodec.php index 00ae218..1321601 100644 --- a/src/Codec/StringCodec.php +++ b/src/Codec/StringCodec.php @@ -166,13 +166,13 @@ class StringCodec implements CodecInterface * @param string[] $components An array of hexadecimal strings representing * the fields of an RFC 4122 UUID * - * @return string[] + * @return string The byte string for the UUID * * @psalm-pure */ - protected function getFields(array $components): array + protected function getFields(array $components): string { - return [ + $fields = [ 'time_low' => str_pad($components[0], 8, '0', STR_PAD_LEFT), 'time_mid' => str_pad($components[1], 4, '0', STR_PAD_LEFT), 'time_hi_and_version' => str_pad($components[2], 4, '0', STR_PAD_LEFT), @@ -180,5 +180,7 @@ class StringCodec implements CodecInterface 'clock_seq_low' => str_pad(substr($components[3], 2), 2, '0', STR_PAD_LEFT), 'node' => str_pad($components[4], 12, '0', STR_PAD_LEFT), ]; + + return (string) hex2bin(implode('', $fields)); } } diff --git a/src/Guid/GuidBuilder.php b/src/Guid/GuidBuilder.php index 5d4ae91..5fba49f 100644 --- a/src/Guid/GuidBuilder.php +++ b/src/Guid/GuidBuilder.php @@ -57,17 +57,15 @@ class GuidBuilder implements UuidBuilderInterface * Builds and returns a Guid * * @param CodecInterface $codec The codec to use for building this Guid instance - * @param string[] $fields An array of fields from which to construct a Guid instance. + * @param string $bytes The byte string from which to construct a UUID * * @return Guid The GuidBuilder returns an instance of Ramsey\Uuid\Guid\Guid */ - public function build(CodecInterface $codec, array $fields): UuidInterface + public function build(CodecInterface $codec, string $bytes): UuidInterface { try { - $fields = new Fields((string) hex2bin(implode('', $fields))); - return new Guid( - $fields, + new Fields($bytes), $this->numberConverter, $codec, $this->timeConverter diff --git a/src/Nonstandard/UuidBuilder.php b/src/Nonstandard/UuidBuilder.php index fac2d05..ea8dd88 100644 --- a/src/Nonstandard/UuidBuilder.php +++ b/src/Nonstandard/UuidBuilder.php @@ -57,18 +57,16 @@ class UuidBuilder implements UuidBuilderInterface * Builds and returns a Nonstandard\Uuid * * @param CodecInterface $codec The codec to use for building this instance - * @param string[] $fields An array of fields from which to construct an instance. + * @param string $bytes The byte string from which to construct a UUID * * @return Uuid The Nonstandard\UuidBuilder returns an instance of * Nonstandard\Uuid */ - public function build(CodecInterface $codec, array $fields): UuidInterface + public function build(CodecInterface $codec, string $bytes): UuidInterface { try { - $fields = new Fields((string) hex2bin(implode('', $fields))); - return new Uuid( - $fields, + new Fields($bytes), $this->numberConverter, $codec, $this->timeConverter diff --git a/src/Rfc4122/UuidBuilder.php b/src/Rfc4122/UuidBuilder.php index fa4d9e5..94d9b6e 100644 --- a/src/Rfc4122/UuidBuilder.php +++ b/src/Rfc4122/UuidBuilder.php @@ -61,14 +61,14 @@ class UuidBuilder implements UuidBuilderInterface * Builds and returns a Uuid * * @param CodecInterface $codec The codec to use for building this Uuid instance - * @param string[] $fields An array of fields from which to construct a Uuid instance + * @param string $bytes The byte string from which to construct a UUID * * @return Rfc4122UuidInterface UuidBuilder returns instances of Rfc4122UuidInterface */ - public function build(CodecInterface $codec, array $fields): UuidInterface + public function build(CodecInterface $codec, string $bytes): UuidInterface { try { - $fields = new Fields((string) hex2bin(implode('', $fields))); + $fields = new Fields($bytes); if ($fields->isNil()) { return new NilUuid($fields, $this->numberConverter, $codec, $this->timeConverter); diff --git a/src/UuidFactory.php b/src/UuidFactory.php index b5a8f43..32ab1b4 100644 --- a/src/UuidFactory.php +++ b/src/UuidFactory.php @@ -292,20 +292,19 @@ class UuidFactory implements UuidFactoryInterface } /** - * Returns a Uuid created from the provided fields + * Returns a Uuid created from the provided byte string * - * Uses the configured builder and codec and the provided array of - * hexadecimal-value UUID fields to construct a Uuid object. + * Uses the configured builder and codec and the provided byte string to + * construct a Uuid object. * - * @param string[] $fields An array of fields from which to construct a UUID; - * see {@see \Ramsey\Uuid\UuidInterface::getFieldsHex()} for array structure + * @param string $bytes The byte string from which to construct a UUID * * @return UuidInterface An instance of UuidInterface, created from the - * provided fields + * provided bytes */ - public function uuid(array $fields): UuidInterface + public function uuid(string $bytes): UuidInterface { - return $this->uuidBuilder->build($this->codec, $fields); + return $this->uuidBuilder->build($this->codec, $bytes); } /** @@ -354,6 +353,6 @@ class UuidFactory implements UuidFactoryInterface 'node' => substr($hash, 20, 12), ]; - return $this->uuid($fields); + return $this->uuid((string) hex2bin(implode('', $fields))); } } diff --git a/tests/Builder/DefaultUuidBuilderTest.php b/tests/Builder/DefaultUuidBuilderTest.php index b36c51d..5325b1c 100644 --- a/tests/Builder/DefaultUuidBuilderTest.php +++ b/tests/Builder/DefaultUuidBuilderTest.php @@ -31,7 +31,9 @@ class DefaultUuidBuilderTest extends TestCase 'node' => 'be0725c8ce01', ]; - $result = $builder->build($codec, $fields); + $bytes = (string) hex2bin(implode('', $fields)); + + $result = $builder->build($codec, $bytes); $this->assertInstanceOf(Uuid::class, $result); } } diff --git a/tests/Builder/FallbackBuilderTest.php b/tests/Builder/FallbackBuilderTest.php index 36f373e..fec5f29 100644 --- a/tests/Builder/FallbackBuilderTest.php +++ b/tests/Builder/FallbackBuilderTest.php @@ -17,27 +17,27 @@ class FallbackBuilderTest extends TestCase public function testBuildThrowsExceptionAfterAllConfiguredBuildersHaveErrored(): void { $codec = Mockery::mock(CodecInterface::class); - $fields = ['someFields']; + $bytes = 'foobar'; $builder1 = Mockery::mock(UuidBuilderInterface::class); $builder1 ->shouldReceive('build') ->once() - ->with($codec, $fields) + ->with($codec, $bytes) ->andThrow(UnableToBuildUuidException::class); $builder2 = Mockery::mock(UuidBuilderInterface::class); $builder2 ->shouldReceive('build') ->once() - ->with($codec, $fields) + ->with($codec, $bytes) ->andThrow(UnableToBuildUuidException::class); $builder3 = Mockery::mock(UuidBuilderInterface::class); $builder3 ->shouldReceive('build') ->once() - ->with($codec, $fields) + ->with($codec, $bytes) ->andThrow(UnableToBuildUuidException::class); $fallbackBuilder = new FallbackBuilder([$builder1, $builder2, $builder3]); @@ -47,6 +47,6 @@ class FallbackBuilderTest extends TestCase 'Could not find a suitable builder for the provided codec and fields' ); - $fallbackBuilder->build($codec, $fields); + $fallbackBuilder->build($codec, $bytes); } } diff --git a/tests/Codec/StringCodecTest.php b/tests/Codec/StringCodecTest.php index 92e4d25..f8b4ac0 100644 --- a/tests/Codec/StringCodecTest.php +++ b/tests/Codec/StringCodecTest.php @@ -88,10 +88,12 @@ class StringCodecTest extends TestCase 'node' => $this->fields->getNode()->toString(), ]; + $bytes = hex2bin(implode('', $fields)); + $string = 'uuid:12345678-1234-4bcd-abef-1234abcd4321'; $this->builder->expects($this->once()) ->method('build') - ->with($this->isInstanceOf(StringCodec::class), $fields); + ->with($this->isInstanceOf(StringCodec::class), $bytes); $codec = new StringCodec($this->builder); $codec->decode($string); } diff --git a/tests/Encoder/TimestampFirstCombCodecTest.php b/tests/Encoder/TimestampFirstCombCodecTest.php index d73ac3a..3544fff 100644 --- a/tests/Encoder/TimestampFirstCombCodecTest.php +++ b/tests/Encoder/TimestampFirstCombCodecTest.php @@ -63,14 +63,14 @@ class TimestampFirstCombCodecTest extends TestCase ->method('build') ->with( $this->codec, - [ + hex2bin(implode('', [ 'time_low' => 'ff6f8cb0', 'time_mid' => 'c57d', 'time_hi_and_version' => '11e1', 'clock_seq_hi_and_reserved' => '9b', 'clock_seq_low' => '21', 'node' => '0800200c9a66', - ] + ])) ); $this->codec->decode('0800200c-9a66-11e1-9b21-ff6f8cb0c57d'); } @@ -81,14 +81,14 @@ class TimestampFirstCombCodecTest extends TestCase ->method('build') ->with( $this->codec, - [ + hex2bin(implode('', [ 'time_low' => 'ff6f8cb0', 'time_mid' => 'c57d', 'time_hi_and_version' => '11e1', 'clock_seq_hi_and_reserved' => '9b', 'clock_seq_low' => '21', 'node' => '0800200c9a66', - ] + ])) ); $this->codec->decodeBytes((string) hex2bin('0800200c9a6611e19b21ff6f8cb0c57d')); } diff --git a/tests/Encoder/TimestampLastCombCodecTest.php b/tests/Encoder/TimestampLastCombCodecTest.php index 7ef6c53..3985ecf 100644 --- a/tests/Encoder/TimestampLastCombCodecTest.php +++ b/tests/Encoder/TimestampLastCombCodecTest.php @@ -65,14 +65,14 @@ class TimestampLastCombCodecTest extends TestCase ->method('build') ->with( $this->codec, - [ + hex2bin(implode('', [ 'time_low' => '0800200c', 'time_mid' => '9a66', 'time_hi_and_version' => '11e1', 'clock_seq_hi_and_reserved' => '9b', 'clock_seq_low' => '21', 'node' => 'ff6f8cb0c57d', - ] + ])) ); $this->codec->decode('0800200c-9a66-11e1-9b21-ff6f8cb0c57d'); } @@ -83,14 +83,14 @@ class TimestampLastCombCodecTest extends TestCase ->method('build') ->with( $this->codec, - [ + hex2bin(implode('', [ 'time_low' => '0800200c', 'time_mid' => '9a66', 'time_hi_and_version' => '11e1', 'clock_seq_hi_and_reserved' => '9b', 'clock_seq_low' => '21', 'node' => 'ff6f8cb0c57d', - ] + ])) ); $this->codec->decodeBytes((string) hex2bin('0800200c9a6611e19b21ff6f8cb0c57d')); } diff --git a/tests/Rfc4122/UuidBuilderTest.php b/tests/Rfc4122/UuidBuilderTest.php index ac6b6dd..1fb2d30 100644 --- a/tests/Rfc4122/UuidBuilderTest.php +++ b/tests/Rfc4122/UuidBuilderTest.php @@ -27,7 +27,7 @@ class UuidBuilderTest extends TestCase */ public function testBuild(string $uuid, string $expectedClass, int $expectedVersion): void { - $fields = explode('-', $uuid); + $bytes = (string) hex2bin(str_replace('-', '', $uuid)); $calculator = new BrickMathCalculator(); $numberConverter = new GenericNumberConverter($calculator); @@ -35,7 +35,7 @@ class UuidBuilderTest extends TestCase $builder = new UuidBuilder($numberConverter, $timeConverter); $codec = new StringCodec($builder); - $result = $builder->build($codec, $fields); + $result = $builder->build($codec, $bytes); /** @var Fields $fields */ $fields = $result->getFields(); @@ -80,7 +80,7 @@ class UuidBuilderTest extends TestCase public function testBuildThrowsUnableToBuildException(): void { - $fields = explode('-', 'ff6f8cb0-c57d-51e1-9b21-0800200c9a'); + $bytes = (string) hex2bin(str_replace('-', '', 'ff6f8cb0-c57d-51e1-9b21-0800200c9a')); $calculator = new BrickMathCalculator(); $numberConverter = new GenericNumberConverter($calculator); @@ -93,6 +93,6 @@ class UuidBuilderTest extends TestCase 'The byte string must be 16 bytes long; received 15 bytes' ); - $builder->build($codec, $fields); + $builder->build($codec, $bytes); } }