From df575bdb79660c28f6969053b904ffbece24ac6a Mon Sep 17 00:00:00 2001 From: Ben Ramsey Date: Sun, 22 Jun 2025 17:58:34 -0500 Subject: [PATCH] Re-add the @pure annotations These were removed in 691c2c816ea574eab667268eca85a1d9046ea599 but should remain in the code base. --- src/BinaryUtils.php | 4 ++++ src/Builder/DegradedUuidBuilder.php | 2 ++ src/Builder/FallbackBuilder.php | 2 ++ src/Builder/UuidBuilderInterface.php | 2 ++ src/Converter/Number/BigNumberConverter.php | 6 ++++++ .../Number/GenericNumberConverter.php | 7 ++++++- src/Converter/NumberConverterInterface.php | 4 ++++ src/Converter/TimeConverterInterface.php | 4 ++++ src/Generator/DefaultNameGenerator.php | 3 +++ src/Generator/NameGeneratorInterface.php | 2 ++ src/Generator/PeclUuidNameGenerator.php | 3 +++ src/Guid/GuidBuilder.php | 2 ++ src/Lazy/LazyUuidFromString.php | 3 +++ src/Nonstandard/UuidBuilder.php | 2 ++ src/Rfc4122/UuidBuilder.php | 2 ++ src/Uuid.php | 16 +++++++++++++++ src/UuidFactory.php | 20 +++++++++++++++++++ src/UuidFactoryInterface.php | 10 ++++++++++ src/functions.php | 6 ++++++ 19 files changed, 99 insertions(+), 1 deletion(-) diff --git a/src/BinaryUtils.php b/src/BinaryUtils.php index 1556cfb..d8aac2e 100644 --- a/src/BinaryUtils.php +++ b/src/BinaryUtils.php @@ -27,6 +27,8 @@ class BinaryUtils * @param int $clockSeq The 16-bit clock sequence value before the variant is applied * * @return int The 16-bit clock sequence multiplexed with the UUID variant + * + * @pure */ public static function applyVariant(int $clockSeq): int { @@ -42,6 +44,8 @@ class BinaryUtils * @param int $version The version to apply to the `time_hi` field * * @return int The 16-bit time_hi field of the timestamp multiplexed with the UUID version number + * + * @pure */ public static function applyVersion(int $timeHi, int $version): int { diff --git a/src/Builder/DegradedUuidBuilder.php b/src/Builder/DegradedUuidBuilder.php index 126abd5..40f7b8f 100644 --- a/src/Builder/DegradedUuidBuilder.php +++ b/src/Builder/DegradedUuidBuilder.php @@ -50,6 +50,8 @@ class DegradedUuidBuilder implements UuidBuilderInterface * @param string $bytes The byte string from which to construct a UUID * * @return DegradedUuid The DegradedUuidBuild returns an instance of Ramsey\Uuid\DegradedUuid + * + * @pure */ public function build(CodecInterface $codec, string $bytes): UuidInterface { diff --git a/src/Builder/FallbackBuilder.php b/src/Builder/FallbackBuilder.php index 4b8d797..e40f778 100644 --- a/src/Builder/FallbackBuilder.php +++ b/src/Builder/FallbackBuilder.php @@ -40,6 +40,8 @@ class FallbackBuilder implements UuidBuilderInterface * @param string $bytes The byte string from which to construct a UUID * * @return UuidInterface an instance of a UUID object + * + * @pure */ public function build(CodecInterface $codec, string $bytes): UuidInterface { diff --git a/src/Builder/UuidBuilderInterface.php b/src/Builder/UuidBuilderInterface.php index 630cd1d..c409878 100644 --- a/src/Builder/UuidBuilderInterface.php +++ b/src/Builder/UuidBuilderInterface.php @@ -31,6 +31,8 @@ interface UuidBuilderInterface * @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 + * + * @pure */ public function build(CodecInterface $codec, string $bytes): UuidInterface; } diff --git a/src/Converter/Number/BigNumberConverter.php b/src/Converter/Number/BigNumberConverter.php index 9c51aab..ff4e1cc 100644 --- a/src/Converter/Number/BigNumberConverter.php +++ b/src/Converter/Number/BigNumberConverter.php @@ -34,11 +34,17 @@ class BigNumberConverter implements NumberConverterInterface $this->converter = new GenericNumberConverter(new BrickMathCalculator()); } + /** + * @pure + */ public function fromHex(string $hex): string { return $this->converter->fromHex($hex); } + /** + * @pure + */ public function toHex(string $number): string { return $this->converter->toHex($number); diff --git a/src/Converter/Number/GenericNumberConverter.php b/src/Converter/Number/GenericNumberConverter.php index cb8b331..034dc43 100644 --- a/src/Converter/Number/GenericNumberConverter.php +++ b/src/Converter/Number/GenericNumberConverter.php @@ -29,14 +29,19 @@ class GenericNumberConverter implements NumberConverterInterface { } + /** + * @pure + */ public function fromHex(string $hex): string { return $this->calculator->fromBase($hex, 16)->toString(); } + /** + * @pure + */ public function toHex(string $number): string { - /** @phpstan-ignore-next-line PHPStan complains that this is not a non-empty-string. */ return $this->calculator->toBase(new IntegerObject($number), 16); } } diff --git a/src/Converter/NumberConverterInterface.php b/src/Converter/NumberConverterInterface.php index 98b9baf..63eca6c 100644 --- a/src/Converter/NumberConverterInterface.php +++ b/src/Converter/NumberConverterInterface.php @@ -30,6 +30,8 @@ interface NumberConverterInterface * @param string $hex The hexadecimal string representation to convert * * @return numeric-string String representation of an integer + * + * @pure */ public function fromHex(string $hex): string; @@ -40,6 +42,8 @@ interface NumberConverterInterface * unsigned integers that are greater than `PHP_INT_MAX`. * * @return non-empty-string Hexadecimal string + * + * @pure */ public function toHex(string $number): string; } diff --git a/src/Converter/TimeConverterInterface.php b/src/Converter/TimeConverterInterface.php index 6402407..065e3b7 100644 --- a/src/Converter/TimeConverterInterface.php +++ b/src/Converter/TimeConverterInterface.php @@ -34,6 +34,8 @@ interface TimeConverterInterface * @param string $microseconds A string representation of the micro-seconds associated with the time to calculate * * @return Hexadecimal The full UUID timestamp as a Hexadecimal value + * + * @pure */ public function calculateTime(string $seconds, string $microseconds): Hexadecimal; @@ -44,6 +46,8 @@ interface TimeConverterInterface * of 100-nanosecond intervals since UTC 00:00:00.00, 15 October 1582. * * @return Time An instance of {@see Time} + * + * @pure */ public function convertTime(Hexadecimal $uuidTimestamp): Time; } diff --git a/src/Generator/DefaultNameGenerator.php b/src/Generator/DefaultNameGenerator.php index a73b630..cf37b45 100644 --- a/src/Generator/DefaultNameGenerator.php +++ b/src/Generator/DefaultNameGenerator.php @@ -25,6 +25,9 @@ use function hash; */ class DefaultNameGenerator implements NameGeneratorInterface { + /** + * @pure + */ public function generate(UuidInterface $ns, string $name, string $hashAlgorithm): string { try { diff --git a/src/Generator/NameGeneratorInterface.php b/src/Generator/NameGeneratorInterface.php index d2b20eb..f0fb8da 100644 --- a/src/Generator/NameGeneratorInterface.php +++ b/src/Generator/NameGeneratorInterface.php @@ -30,6 +30,8 @@ interface NameGeneratorInterface * @param string $hashAlgorithm The hashing algorithm to use * * @return string A binary string + * + * @pure */ public function generate(UuidInterface $ns, string $name, string $hashAlgorithm): string; } diff --git a/src/Generator/PeclUuidNameGenerator.php b/src/Generator/PeclUuidNameGenerator.php index 2f6d948..ee77a78 100644 --- a/src/Generator/PeclUuidNameGenerator.php +++ b/src/Generator/PeclUuidNameGenerator.php @@ -29,6 +29,9 @@ use function uuid_parse; */ class PeclUuidNameGenerator implements NameGeneratorInterface { + /** + * @pure + */ public function generate(UuidInterface $ns, string $name, string $hashAlgorithm): string { $uuid = match ($hashAlgorithm) { diff --git a/src/Guid/GuidBuilder.php b/src/Guid/GuidBuilder.php index 836e51a..d5ea663 100644 --- a/src/Guid/GuidBuilder.php +++ b/src/Guid/GuidBuilder.php @@ -49,6 +49,8 @@ class GuidBuilder implements UuidBuilderInterface * @param string $bytes The byte string from which to construct a UUID * * @return Guid The GuidBuilder returns an instance of Ramsey\Uuid\Guid\Guid + * + * @pure */ public function build(CodecInterface $codec, string $bytes): UuidInterface { diff --git a/src/Lazy/LazyUuidFromString.php b/src/Lazy/LazyUuidFromString.php index e3d4b9c..7ec71c2 100644 --- a/src/Lazy/LazyUuidFromString.php +++ b/src/Lazy/LazyUuidFromString.php @@ -61,6 +61,9 @@ final class LazyUuidFromString implements UuidInterface { } + /** + * @pure + */ public static function fromBytes(string $bytes): self { $base16Uuid = bin2hex($bytes); diff --git a/src/Nonstandard/UuidBuilder.php b/src/Nonstandard/UuidBuilder.php index ded4709..a9885cb 100644 --- a/src/Nonstandard/UuidBuilder.php +++ b/src/Nonstandard/UuidBuilder.php @@ -47,6 +47,8 @@ class UuidBuilder implements UuidBuilderInterface * @param string $bytes The byte string from which to construct a UUID * * @return Uuid The Nonstandard\UuidBuilder returns an instance of Nonstandard\Uuid + * + * @pure */ public function build(CodecInterface $codec, string $bytes): UuidInterface { diff --git a/src/Rfc4122/UuidBuilder.php b/src/Rfc4122/UuidBuilder.php index e477528..5c239c2 100644 --- a/src/Rfc4122/UuidBuilder.php +++ b/src/Rfc4122/UuidBuilder.php @@ -60,6 +60,8 @@ class UuidBuilder implements UuidBuilderInterface * @param string $bytes The byte string from which to construct a UUID * * @return Rfc4122UuidInterface UuidBuilder returns instances of Rfc4122UuidInterface + * + * @pure */ public function build(CodecInterface $codec, string $bytes): UuidInterface { diff --git a/src/Uuid.php b/src/Uuid.php index 40ada66..449a789 100644 --- a/src/Uuid.php +++ b/src/Uuid.php @@ -448,6 +448,8 @@ class Uuid implements UuidInterface * @return UuidInterface A UuidInterface instance created from a binary string representation * * @throws InvalidArgumentException + * + * @pure */ public static function fromBytes(string $bytes): UuidInterface { @@ -479,6 +481,8 @@ class Uuid implements UuidInterface * @return UuidInterface A UuidInterface instance created from a hexadecimal string representation * * @throws InvalidArgumentException + * + * @pure */ public static function fromString(string $uuid): UuidInterface { @@ -518,6 +522,8 @@ class Uuid implements UuidInterface * @return UuidInterface A UuidInterface instance created from the Hexadecimal object representing a hexadecimal number * * @throws InvalidArgumentException + * + * @pure */ public static function fromHexadecimal(Hexadecimal $hex): UuidInterface { @@ -541,6 +547,8 @@ class Uuid implements UuidInterface * @return UuidInterface A UuidInterface instance created from the string representation of a 128-bit integer * * @throws InvalidArgumentException + * + * @pure */ public static function fromInteger(string $integer): UuidInterface { @@ -555,6 +563,8 @@ class Uuid implements UuidInterface * @return bool True if the string is a valid UUID, false otherwise * * @phpstan-assert-if-true =non-empty-string $uuid + * + * @pure */ public static function isValid(string $uuid): bool { @@ -606,6 +616,8 @@ class Uuid implements UuidInterface * @param string $name The name to use for creating a UUID * * @return UuidInterface A UuidInterface instance that represents a version 3 UUID + * + * @pure */ public static function uuid3($ns, string $name): UuidInterface { @@ -629,6 +641,8 @@ class Uuid implements UuidInterface * @param string $name The name to use for creating a UUID * * @return UuidInterface A UuidInterface instance that represents a version 5 UUID + * + * @pure */ public static function uuid5($ns, string $name): UuidInterface { @@ -682,6 +696,8 @@ class Uuid implements UuidInterface * and 65 will be replaced with the UUID variant. You MUST NOT rely on these bits for your application needs. * * @return UuidInterface A UuidInterface instance that represents a version 8 UUID + * + * @pure */ public static function uuid8(string $bytes): UuidInterface { diff --git a/src/UuidFactory.php b/src/UuidFactory.php index 1c78a21..19be738 100644 --- a/src/UuidFactory.php +++ b/src/UuidFactory.php @@ -252,11 +252,17 @@ class UuidFactory implements UuidFactoryInterface $this->validator = $validator; } + /** + * @pure + */ public function fromBytes(string $bytes): UuidInterface { return $this->codec->decodeBytes($bytes); } + /** + * @pure + */ public function fromString(string $uuid): UuidInterface { $uuid = strtolower($uuid); @@ -264,6 +270,9 @@ class UuidFactory implements UuidFactoryInterface return $this->codec->decode($uuid); } + /** + * @pure + */ public function fromInteger(string $integer): UuidInterface { $hex = $this->numberConverter->toHex($integer); @@ -284,6 +293,9 @@ class UuidFactory implements UuidFactoryInterface return $this->uuidFromBytesAndVersion($bytes, Uuid::UUID_TYPE_TIME); } + /** + * @pure + */ public function fromHexadecimal(Hexadecimal $hex): UuidInterface { return $this->codec->decode($hex->__toString()); @@ -312,6 +324,7 @@ class UuidFactory implements UuidFactoryInterface /** * @inheritDoc + * @pure */ public function uuid3($ns, string $name): UuidInterface { @@ -327,6 +340,7 @@ class UuidFactory implements UuidFactoryInterface /** * @inheritDoc + * @pure */ public function uuid5($ns, string $name): UuidInterface { @@ -377,6 +391,8 @@ class UuidFactory implements UuidFactoryInterface * and 65 will be replaced with the UUID variant. You MUST NOT rely on these bits for your application needs. * * @return UuidInterface A UuidInterface instance that represents a version 8 UUID + * + * @pure */ public function uuid8(string $bytes): UuidInterface { @@ -391,6 +407,8 @@ class UuidFactory implements UuidFactoryInterface * @param string $bytes The byte string from which to construct a UUID * * @return UuidInterface An instance of UuidInterface, created from the provided bytes + * + * @pure */ public function uuid(string $bytes): UuidInterface { @@ -406,6 +424,8 @@ class UuidFactory implements UuidFactoryInterface * @param string $hashAlgorithm The hashing algorithm to use when hashing together the namespace and name * * @return UuidInterface An instance of UuidInterface, created by hashing together the provided namespace and name + * + * @pure */ private function uuidFromNsAndName( UuidInterface | string $ns, diff --git a/src/UuidFactoryInterface.php b/src/UuidFactoryInterface.php index 2b77526..5a83a79 100644 --- a/src/UuidFactoryInterface.php +++ b/src/UuidFactoryInterface.php @@ -30,6 +30,8 @@ interface UuidFactoryInterface * @param string $bytes A binary string * * @return UuidInterface A UuidInterface instance created from a binary string representation + * + * @pure */ public function fromBytes(string $bytes): UuidInterface; @@ -55,6 +57,8 @@ interface UuidFactoryInterface * @param string $integer String representation of 128-bit integer * * @return UuidInterface A UuidInterface instance created from the string representation of a 128-bit integer + * + * @pure */ public function fromInteger(string $integer): UuidInterface; @@ -64,6 +68,8 @@ interface UuidFactoryInterface * @param string $uuid A hexadecimal string * * @return UuidInterface A UuidInterface instance created from a hexadecimal string representation + * + * @pure */ public function fromString(string $uuid): UuidInterface; @@ -112,6 +118,8 @@ interface UuidFactoryInterface * @param string $name The name to use for creating a UUID * * @return UuidInterface A UuidInterface instance that represents a version 3 UUID + * + * @pure */ public function uuid3($ns, string $name): UuidInterface; @@ -129,6 +137,8 @@ interface UuidFactoryInterface * @param string $name The name to use for creating a UUID * * @return UuidInterface A UuidInterface instance that represents a version 5 UUID + * + * @pure */ public function uuid5($ns, string $name): UuidInterface; diff --git a/src/functions.php b/src/functions.php index 946cfbc..854c5c5 100644 --- a/src/functions.php +++ b/src/functions.php @@ -62,6 +62,8 @@ function v2( * @param UuidInterface | string $ns The namespace (must be a valid UUID) * * @return non-empty-string Version 3 UUID as a string + * + * @pure */ function v3($ns, string $name): string { @@ -84,6 +86,8 @@ function v4(): string * @param UuidInterface | string $ns The namespace (must be a valid UUID) * * @return non-empty-string Version 5 UUID as a string + * + * @pure */ function v5($ns, string $name): string { @@ -128,6 +132,8 @@ function v7(?DateTimeInterface $dateTime = null): string * 65 will be replaced with the UUID variant. You MUST NOT rely on these bits for your application needs. * * @return non-empty-string Version 8 UUID as a string + * + * @pure */ function v8(string $bytes): string {