feat: rename RandomGenerator to BytesGenerator

ramsey · Oct 22, 2022 · 5658f8a · 5658f8a
1 parent 6f8da42
commit 5658f8a
Show file tree

Hide file tree

Showing 13 changed files with 105 additions and 96 deletions.
diff --git a/...rvice/RandomGenerator/RandomGenerator.php → ...Service/BytesGenerator/BytesGenerator.php b/...rvice/RandomGenerator/RandomGenerator.php → ...Service/BytesGenerator/BytesGenerator.php
@@ -14,21 +14,27 @@
 
 declare(strict_types=1);
 
-namespace Ramsey\Identifier\Service\RandomGenerator;
+namespace Ramsey\Identifier\Service\BytesGenerator;
+
+use DateTimeInterface;
 
 /**
- * Defines a random generator interface for generating pseudorandom bytes
+ * Defines a bytes generator interface for generating bytes used to create
+ * identifiers
  */
-interface RandomGenerator
+interface BytesGenerator
 {
     /**
-     * Generates an n-length string of random bytes
+     * Generates an n-length string of bytes
      *
      * @param int $length The number of bytes to generate
+     * @param DateTimeInterface | null $dateTime An optional date-time instance
+     *     to use when generating the bytes; not all generators will need or use
+     *     this parameter
      *
      * @return non-empty-string
      *
      * @psalm-param positive-int $length
      */
-    public function bytes(int $length): string;
+    public function bytes(int $length, ?DateTimeInterface $dateTime = null): string;
 }
diff --git a/...RandomGenerator/FrozenRandomGenerator.php → ...ce/BytesGenerator/FixedBytesGenerator.php b/...RandomGenerator/FrozenRandomGenerator.php → ...ce/BytesGenerator/FixedBytesGenerator.php
@@ -14,16 +14,17 @@
 
 declare(strict_types=1);
 
-namespace Ramsey\Identifier\Service\RandomGenerator;
+namespace Ramsey\Identifier\Service\BytesGenerator;
+
+use DateTimeInterface;
 
 use function strlen;
 use function substr;
 
 /**
- * A random generator that isn't random and returns a pre-determined string
- * of bytes
+ * A bytes generator that returns a pre-determined string of bytes
  */
-final class FrozenRandomGenerator implements RandomGenerator
+final class FixedBytesGenerator implements BytesGenerator
 {
     /**
      * @param non-empty-string $bytes
@@ -32,7 +33,7 @@ public function __construct(private readonly string $bytes)
     {
     }
 
-    public function bytes(int $length): string
+    public function bytes(int $length, ?DateTimeInterface $dateTime = null): string
     {
         if (strlen($this->bytes) > $length) {
             /** @var non-empty-string */

diff --git a/...ce/RandomGenerator/PhpRandomGenerator.php → ...e/BytesGenerator/RandomBytesGenerator.php b/...ce/RandomGenerator/PhpRandomGenerator.php → ...e/BytesGenerator/RandomBytesGenerator.php
@@ -14,7 +14,9 @@
 
 declare(strict_types=1);
 
-namespace Ramsey\Identifier\Service\RandomGenerator;
+namespace Ramsey\Identifier\Service\BytesGenerator;
+
+use DateTimeInterface;
 
 use function random_bytes;
 
@@ -24,9 +26,9 @@
  *
  * @link https://www.php.net/random_bytes random_bytes()
  */
-final class PhpRandomGenerator implements RandomGenerator
+final class RandomBytesGenerator implements BytesGenerator
 {
-    public function bytes(int $length): string
+    public function bytes(int $length, ?DateTimeInterface $dateTime = null): string
     {
         return random_bytes($length);
     }

diff --git a/src/Ulid/DefaultUlidFactory.php b/src/Ulid/DefaultUlidFactory.php
@@ -21,9 +21,9 @@
 use Brick\Math\Exception\NegativeNumberException;
 use DateTimeInterface;
 use Ramsey\Identifier\Exception\InvalidArgument;
+use Ramsey\Identifier\Service\BytesGenerator\BytesGenerator;
+use Ramsey\Identifier\Service\BytesGenerator\RandomBytesGenerator;
 use Ramsey\Identifier\Service\Clock\SystemClock;
-use Ramsey\Identifier\Service\RandomGenerator\PhpRandomGenerator;
-use Ramsey\Identifier\Service\RandomGenerator\RandomGenerator;
 use Ramsey\Identifier\Ulid\Utility\Validation;
 use Ramsey\Identifier\UlidFactory;
 use Ramsey\Identifier\UlidIdentifier;
@@ -57,12 +57,12 @@ final class DefaultUlidFactory implements UlidFactory
      *
      * @param Clock $clock A clock used to provide a date-time instance;
      *     defaults to {@see SystemClock}
-     * @param RandomGenerator $randomGenerator A random generator used to
-     *     generate bytes; defaults to {@see PhpRandomGenerator}
+     * @param BytesGenerator $randomGenerator A random generator used to
+     *     generate bytes; defaults to {@see RandomBytesGenerator}
      */
     public function __construct(
         private readonly Clock $clock = new SystemClock(),
-        private readonly RandomGenerator $randomGenerator = new PhpRandomGenerator(),
+        private readonly BytesGenerator $randomGenerator = new RandomBytesGenerator(),
     ) {
         $this->time = new Time();
     }

diff --git a/src/Uuid/MicrosoftGuidFactory.php b/src/Uuid/MicrosoftGuidFactory.php
@@ -23,8 +23,8 @@
 use Identifier\StringIdentifierFactory;
 use Ramsey\Identifier\Exception\BadMethodCall;
 use Ramsey\Identifier\Exception\InvalidArgument;
-use Ramsey\Identifier\Service\RandomGenerator\PhpRandomGenerator;
-use Ramsey\Identifier\Service\RandomGenerator\RandomGenerator;
+use Ramsey\Identifier\Service\BytesGenerator\BytesGenerator;
+use Ramsey\Identifier\Service\BytesGenerator\RandomBytesGenerator;
 use Ramsey\Identifier\Uuid\Utility\Binary;
 use Ramsey\Identifier\Uuid\Utility\StandardUuidFactory;
 use Throwable;
@@ -54,11 +54,11 @@ final class MicrosoftGuidFactory implements
     /**
      * Constructs a factory for creating Microsoft GUIDs
      *
-     * @param RandomGenerator $randomGenerator A random generator used to
-     *     generate bytes; defaults to {@see PhpRandomGenerator}
+     * @param BytesGenerator $randomGenerator A random generator used to
+     *     generate bytes; defaults to {@see RandomBytesGenerator}
      */
     public function __construct(
-        private readonly RandomGenerator $randomGenerator = new PhpRandomGenerator(),
+        private readonly BytesGenerator $randomGenerator = new RandomBytesGenerator(),
     ) {
         $this->binary = new Binary();
     }

diff --git a/src/Uuid/UuidV4Factory.php b/src/Uuid/UuidV4Factory.php
@@ -20,8 +20,8 @@
 use Identifier\IntegerIdentifierFactory;
 use Identifier\StringIdentifierFactory;
 use Ramsey\Identifier\Exception\InvalidArgument;
-use Ramsey\Identifier\Service\RandomGenerator\PhpRandomGenerator;
-use Ramsey\Identifier\Service\RandomGenerator\RandomGenerator;
+use Ramsey\Identifier\Service\BytesGenerator\BytesGenerator;
+use Ramsey\Identifier\Service\BytesGenerator\RandomBytesGenerator;
 use Ramsey\Identifier\Uuid\Utility\Binary;
 use Ramsey\Identifier\Uuid\Utility\StandardUuidFactory;
 
@@ -37,11 +37,11 @@ final class UuidV4Factory implements BinaryIdentifierFactory, IntegerIdentifierF
     /**
      * Constructs a factory for creating version 4, random UUIDs
      *
-     * @param RandomGenerator $randomGenerator A random generator used to
-     *     generate bytes; defaults to {@see PhpRandomGenerator}
+     * @param BytesGenerator $randomGenerator A random generator used to
+     *     generate bytes; defaults to {@see RandomBytesGenerator}
      */
     public function __construct(
-        private readonly RandomGenerator $randomGenerator = new PhpRandomGenerator(),
+        private readonly BytesGenerator $randomGenerator = new RandomBytesGenerator(),
     ) {
         $this->binary = new Binary();
     }

diff --git a/src/Uuid/UuidV7Factory.php b/src/Uuid/UuidV7Factory.php
@@ -23,11 +23,11 @@
 use Identifier\IntegerIdentifierFactory;
 use Identifier\StringIdentifierFactory;
 use Ramsey\Identifier\Exception\InvalidArgument;
+use Ramsey\Identifier\Service\BytesGenerator\BytesGenerator;
+use Ramsey\Identifier\Service\BytesGenerator\RandomBytesGenerator;
 use Ramsey\Identifier\Service\Clock\SystemClock;
 use Ramsey\Identifier\Service\Os\Os;
 use Ramsey\Identifier\Service\Os\PhpOs;
-use Ramsey\Identifier\Service\RandomGenerator\PhpRandomGenerator;
-use Ramsey\Identifier\Service\RandomGenerator\RandomGenerator;
 use Ramsey\Identifier\Uuid\Utility\StandardUuidFactory;
 use StellaMaris\Clock\ClockInterface as Clock;
 
@@ -77,12 +77,12 @@ final class UuidV7Factory implements
      *
      * @param Clock $clock A clock used to provide a date-time instance;
      *     defaults to {@see SystemClock}
-     * @param RandomGenerator $randomGenerator A random generator used to
-     *     generate bytes; defaults to {@see PhpRandomGenerator}
+     * @param BytesGenerator $randomGenerator A random generator used to
+     *     generate bytes; defaults to {@see RandomBytesGenerator}
      */
     public function __construct(
         private readonly Clock $clock = new SystemClock(),
-        private readonly RandomGenerator $randomGenerator = new PhpRandomGenerator(),
+        private readonly BytesGenerator $randomGenerator = new RandomBytesGenerator(),
         private readonly Os $os = new PhpOs(),
     ) {
     }

diff --git a/tests/unit/Service/BytesGenerator/FixedBytesGeneratorTest.php b/tests/unit/Service/BytesGenerator/FixedBytesGeneratorTest.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ramsey\Test\Identifier\Service\BytesGenerator;
+
+use Ramsey\Identifier\Service\BytesGenerator\FixedBytesGenerator;
+use Ramsey\Test\Identifier\TestCase;
+
+class FixedBytesGeneratorTest extends TestCase
+{
+    public function testGetBytesWithLengthExactlyAsValueProvided(): void
+    {
+        $bytes = "\xab\xcd\xef\x01\x23\x45\x67\x89";
+        $randomGenerator = new FixedBytesGenerator($bytes);
+
+        $this->assertSame($bytes, $randomGenerator->bytes(8));
+    }
+
+    public function testGetBytesWithLengthGreaterThanValueProvided(): void
+    {
+        $bytes = "\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff";
+        $randomGenerator = new FixedBytesGenerator($bytes);
+
+        $this->assertSame($bytes, $randomGenerator->bytes(20));
+    }
+
+    public function testGetBytesWithLengthLessThanValueProvided(): void
+    {
+        $bytes = "\xff\xff\xff\xff\xab\xcd\xef\x01\x23\x45\x67\x89\xff\xff\xff\xff";
+        $randomGenerator = new FixedBytesGenerator($bytes);
+
+        $this->assertSame("\xff\xff\xff\xff\xab\xcd\xef\x01", $randomGenerator->bytes(8));
+    }
+}
diff --git a/tests/unit/Service/BytesGenerator/RandomBytesGeneratorTest.php b/tests/unit/Service/BytesGenerator/RandomBytesGeneratorTest.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ramsey\Test\Identifier\Service\BytesGenerator;
+
+use Ramsey\Identifier\Service\BytesGenerator\RandomBytesGenerator;
+use Ramsey\Test\Identifier\TestCase;
+
+use function strlen;
+
+class RandomBytesGeneratorTest extends TestCase
+{
+    public function testGetRandomBytes(): void
+    {
+        $randomGenerator = new RandomBytesGenerator();
+
+        $this->assertSame(16, strlen($randomGenerator->bytes(16)));
+    }
+}
diff --git a/tests/unit/Service/RandomGenerator/FrozenRandomGeneratorTest.php b/tests/unit/Service/RandomGenerator/FrozenRandomGeneratorTest.php
diff --git a/tests/unit/Service/RandomGenerator/PhpRandomGeneratorTest.php b/tests/unit/Service/RandomGenerator/PhpRandomGeneratorTest.php
diff --git a/tests/unit/Ulid/DefaultUlidFactoryTest.php b/tests/unit/Ulid/DefaultUlidFactoryTest.php
@@ -6,8 +6,8 @@
 
 use DateTimeImmutable;
 use Ramsey\Identifier\Exception\InvalidArgument;
+use Ramsey\Identifier\Service\BytesGenerator\FixedBytesGenerator;
 use Ramsey\Identifier\Service\Clock\FrozenClock;
-use Ramsey\Identifier\Service\RandomGenerator\FrozenRandomGenerator;
 use Ramsey\Identifier\Ulid\DefaultUlidFactory;
 use Ramsey\Identifier\Ulid\MaxUlid;
 use Ramsey\Identifier\Ulid\NilUlid;
@@ -40,7 +40,7 @@ public function testCreateWithFactoryDeterministicValues(): void
     {
         $factory = new DefaultUlidFactory(
             new FrozenClock(new DateTimeImmutable('1970-01-01 00:00:00')),
-            new FrozenRandomGenerator("\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"),
+            new FixedBytesGenerator("\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"),
         );
 
         $ulid = $factory->create();

diff --git a/tests/unit/Uuid/UuidV7FactoryTest.php b/tests/unit/Uuid/UuidV7FactoryTest.php
@@ -6,9 +6,9 @@
 
 use DateTimeImmutable;
 use Ramsey\Identifier\Exception\InvalidArgument;
+use Ramsey\Identifier\Service\BytesGenerator\FixedBytesGenerator;
 use Ramsey\Identifier\Service\Clock\FrozenClock;
 use Ramsey\Identifier\Service\Os\Os;
-use Ramsey\Identifier\Service\RandomGenerator\FrozenRandomGenerator;
 use Ramsey\Identifier\Uuid\UuidV7;
 use Ramsey\Identifier\Uuid\UuidV7Factory;
 use Ramsey\Test\Identifier\TestCase;
@@ -48,7 +48,7 @@ public function testCreateWithFactoryInitializedValues(): void
     {
         $factory = new UuidV7Factory(
             new FrozenClock(new DateTimeImmutable('1970-01-01 00:00:00.000000')),
-            new FrozenRandomGenerator("\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"),
+            new FixedBytesGenerator("\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"),
         );
 
         $uuid = $factory->create();
@@ -230,7 +230,7 @@ public function testCreateEachUuidIsMonotonicallyIncreasingOn32BitPath(): void
     public function testCreateWithMaximumRandomSeedValue(): void
     {
         $factory = new UuidV7Factory(
-            randomGenerator: new FrozenRandomGenerator(
+            randomGenerator: new FixedBytesGenerator(
                 "\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff",
             ),
         );
@@ -257,7 +257,7 @@ public function testCreateWithMaximumRandomSeedValueOn32BitPath(): void
         ]);
 
         $factory = new UuidV7Factory(
-            randomGenerator: new FrozenRandomGenerator(
+            randomGenerator: new FixedBytesGenerator(
                 "\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff",
             ),
             os: $os,
@@ -284,7 +284,7 @@ public function testCreateWithMaximumRandomSeedValueWithTimeAtMaximumNines(): vo
 
         $factory = new UuidV7Factory(
             clock: new FrozenClock($date),
-            randomGenerator: new FrozenRandomGenerator(
+            randomGenerator: new FixedBytesGenerator(
                 "\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff",
             ),
         );
@@ -313,7 +313,7 @@ public function testCreateWithMaximumRandomSeedValueWithTimeAtMaximumNinesOn32Bi
 
         $factory = new UuidV7Factory(
             clock: new FrozenClock($date),
-            randomGenerator: new FrozenRandomGenerator(
+            randomGenerator: new FixedBytesGenerator(
                 "\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff",
             ),
             os: $os,