From 483b9c9de0b6ff9bcd52615a94f89d58cae6a4d5 Mon Sep 17 00:00:00 2001 From: Ben Ramsey Date: Sat, 13 Aug 2022 10:43:35 -0500 Subject: [PATCH] feat: narrow the clock sequence type hints --- phpstan.neon.dist | 12 +++++++++++ src/DeprecatedUuidFactoryInterface.php | 14 ++++++------- src/Generator/DceSecurityGenerator.php | 1 + .../DceSecurityGeneratorInterface.php | 6 +++--- src/Generator/TimeGeneratorInterface.php | 6 +++--- src/Uuid.php | 20 +++++++++---------- src/functions.php | 16 +++++++-------- tests/Generator/DceSecurityGeneratorTest.php | 2 ++ tests/Generator/DefaultTimeGeneratorTest.php | 2 +- tests/benchmark/UuidGenerationBench.php | 2 +- 10 files changed, 48 insertions(+), 33 deletions(-) diff --git a/phpstan.neon.dist b/phpstan.neon.dist index acd9320..c90f431 100644 --- a/phpstan.neon.dist +++ b/phpstan.neon.dist @@ -11,3 +11,15 @@ parameters: message: '#^Comparison operation ">" between 6 and 0 is always true\.$#' count: 1 path: ./src/Generator/CombGenerator.php + - + message: '#^Result of \|\| is always false\.$#' + count: 1 + path: ./src/Generator/DceSecurityGenerator.php + - + message: '#^Comparison operation ">" between int<0, 63>\|null and 63 is always false\.$#' + count: 1 + path: ./src/Generator/DceSecurityGenerator.php + - + message: '#^Comparison operation "<" between int<0, 63>\|null and 0 is always false\.$#' + count: 1 + path: ./src/Generator/DceSecurityGenerator.php diff --git a/src/DeprecatedUuidFactoryInterface.php b/src/DeprecatedUuidFactoryInterface.php index c450ff9..8c921ab 100644 --- a/src/DeprecatedUuidFactoryInterface.php +++ b/src/DeprecatedUuidFactoryInterface.php @@ -72,7 +72,7 @@ interface DeprecatedUuidFactoryInterface * @param Hexadecimal|positive-int|non-empty-string|null $node A 48-bit * number representing the hardware address; this number may be * represented as an integer or a hexadecimal string - * @param positive-int|null $clockSeq A 14-bit number used to help avoid + * @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 * @@ -97,9 +97,9 @@ interface DeprecatedUuidFactoryInterface * if the local domain is org * @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, 63>|null $clockSeq A 6-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 2 UUID @@ -169,9 +169,9 @@ interface DeprecatedUuidFactoryInterface * * @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 6 UUID diff --git a/src/Generator/DceSecurityGenerator.php b/src/Generator/DceSecurityGenerator.php index de0c71f..2b59343 100644 --- a/src/Generator/DceSecurityGenerator.php +++ b/src/Generator/DceSecurityGenerator.php @@ -124,6 +124,7 @@ class DceSecurityGenerator implements DceSecurityGeneratorInterface // Shift the clock sequence 8 bits to the left, so it matches 0x3f00. if ($clockSeq !== null) { + /** @var int<0, 16383> $clockSeq */ $clockSeq = $clockSeq << 8; } diff --git a/src/Generator/DceSecurityGeneratorInterface.php b/src/Generator/DceSecurityGeneratorInterface.php index 4912224..2eb9dc6 100644 --- a/src/Generator/DceSecurityGeneratorInterface.php +++ b/src/Generator/DceSecurityGeneratorInterface.php @@ -38,9 +38,9 @@ interface DceSecurityGeneratorInterface * if the local domain is org * @param Hexadecimal|positive-int|non-empty-string|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, 63>|null $clockSeq A 6-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 non-empty-string A binary string */ diff --git a/src/Generator/TimeGeneratorInterface.php b/src/Generator/TimeGeneratorInterface.php index 7103e0e..d77fddb 100644 --- a/src/Generator/TimeGeneratorInterface.php +++ b/src/Generator/TimeGeneratorInterface.php @@ -28,9 +28,9 @@ interface TimeGeneratorInterface * @param Hexadecimal|non-empty-string|positive-int|null $node A 48-bit * number representing the hardware address; this number may be * represented as an integer or a hexadecimal 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 + * @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 non-empty-string A binary string */ diff --git a/src/Uuid.php b/src/Uuid.php index 770f31d..c0be7ae 100644 --- a/src/Uuid.php +++ b/src/Uuid.php @@ -442,9 +442,9 @@ class Uuid implements Rfc4122UuidInterface * @param Hexadecimal|positive-int|non-empty-string|null $node A 48-bit * number representing the hardware address; this number may be * represented as an integer or a hexadecimal string - * @param positive-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 @@ -466,10 +466,10 @@ class Uuid implements Rfc4122UuidInterface * if the local domain is org * @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 (in a version 2 UUID, the lower 8 bits of this number - * are replaced with the domain). + * @param int<0, 63>|null $clockSeq A 6-bit number used to help avoid + * duplicates that could arise when the clock is set backwards in time + * or if the node ID changes (in a version 2 UUID, the lower 8 bits of + * this number are replaced with the domain) * * @return UuidInterface A UuidInterface instance that represents a * version 2 UUID @@ -546,9 +546,9 @@ class Uuid implements Rfc4122UuidInterface * * @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 6 UUID diff --git a/src/functions.php b/src/functions.php index aa956e9..7bc5fb4 100644 --- a/src/functions.php +++ b/src/functions.php @@ -25,7 +25,7 @@ use Ramsey\Uuid\Type\Integer as IntegerObject; * @param Hexadecimal|positive-int|non-empty-string|null $node A 48-bit number * representing the hardware address; this number may be represented as an * integer or a hexadecimal string - * @param positive-int|null $clockSeq A 14-bit number used to help avoid + * @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 * @@ -48,9 +48,9 @@ function v1(Hexadecimal | int | string | null $node = null, ?int $clockSeq = nul * if the local domain is org * @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, 63>|null $clockSeq A 6-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 non-empty-string Version 2 UUID as a string */ @@ -108,14 +108,14 @@ function v5(UuidInterface | string $ns, string $name): string } /** - * Returns a version 6 (ordered-time) UUID from a host ID, sequence number, + * Returns a version 6 (reordered-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|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 non-empty-string Version 6 UUID as a string */ diff --git a/tests/Generator/DceSecurityGeneratorTest.php b/tests/Generator/DceSecurityGeneratorTest.php index 63e7932..ca53096 100644 --- a/tests/Generator/DceSecurityGeneratorTest.php +++ b/tests/Generator/DceSecurityGeneratorTest.php @@ -225,6 +225,7 @@ class DceSecurityGeneratorTest extends TestCase 'Clock sequence out of bounds; it must be a value between 0 and 63' ); + // @phpstan-ignore-next-line $dceSecurityGenerator->generate(Uuid::DCE_DOMAIN_ORG, null, null, -1); } @@ -241,6 +242,7 @@ class DceSecurityGeneratorTest extends TestCase 'Clock sequence out of bounds; it must be a value between 0 and 63' ); + // @phpstan-ignore-next-line $dceSecurityGenerator->generate(Uuid::DCE_DOMAIN_ORG, null, null, 64); } diff --git a/tests/Generator/DefaultTimeGeneratorTest.php b/tests/Generator/DefaultTimeGeneratorTest.php index 706477d..c854385 100644 --- a/tests/Generator/DefaultTimeGeneratorTest.php +++ b/tests/Generator/DefaultTimeGeneratorTest.php @@ -43,7 +43,7 @@ class DefaultTimeGeneratorTest extends TestCase private Hexadecimal $calculatedTime; /** - * @var positive-int + * @var int<0, 16383> */ private int $clockSeq = 4066; diff --git a/tests/benchmark/UuidGenerationBench.php b/tests/benchmark/UuidGenerationBench.php index e1f3281..88b1c19 100644 --- a/tests/benchmark/UuidGenerationBench.php +++ b/tests/benchmark/UuidGenerationBench.php @@ -23,7 +23,7 @@ use Ramsey\Uuid\UuidInterface; final class UuidGenerationBench { /** - * @var positive-int + * @var int<0, 16383> */ private int $clockSequence;