contrib/php-uuid
1
0
Fork 0
mirror of https://github.com/ramsey/uuid.git synced 2026-06-14 15:56:48 +03:00
Code Issues Packages Projects Releases Wiki Activity

Clean up docblocks, code, and note new deprecations

Browse Source 
The following are deprecated:

* `Ramsey\Uuid\Codec\OrderedTimeCodec`
* `Ramsey\Uuid\Codec\TimestampFirstCombCodec`
* `Ramsey\Uuid\Codec\TimestampLastCombCodec`
* `Ramsey\Uuid\Generator\CombGenerator`
This commit is contained in:
Ben Ramsey
2025-05-31 17:20:12 -05:00
parent 7eec9c2202
commit 6bd7221484
101 changed files with 1023 additions and 1582 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/BinaryUtils.php
+10 -19
View File
@@ -20,40 +20,31 @@ namespace Ramsey\Uuid;
class BinaryUtils
{
/**
* Applies the RFC 4122 variant field to the 16-bit clock sequence
* Applies the variant field to the 16-bit clock sequence
*
* @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
*
* @param int $clockSeq The 16-bit clock sequence value before the RFC 4122
* variant is applied
* @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
*/
public static function applyVariant(int $clockSeq): int
{
$clockSeq = $clockSeq & 0x3fff;
$clockSeq |= 0x8000;
return $clockSeq;
return ($clockSeq & 0x3fff) | 0x8000;
}
/**
* Applies the RFC 4122 version number to the 16-bit `time_hi_and_version` field
* Applies the version field to the 16-bit `time_hi_and_version` field
*
* @link http://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
*
* @param int $timeHi The value of the 16-bit `time_hi_and_version` field
* before the RFC 4122 version is applied
* @param int $version The RFC 4122 version to apply to the `time_hi` field
* @param int $timeHi The value of the 16-bit `time_hi_and_version` field before the version is applied
* @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
* @return int The 16-bit time_hi field of the timestamp multiplexed with the UUID version number
*/
public static function applyVersion(int $timeHi, int $version): int
{
$timeHi = $timeHi & 0x0fff;
$timeHi |= $version << 12;
return $timeHi;
return ($timeHi & 0x0fff) | ($version << 12);
}
}
src/Builder/BuilderCollection.php
+6 -7
View File
@@ -27,10 +27,10 @@ use Traversable;
/**
* A collection of UuidBuilderInterface objects
*
* @deprecated this class has been deprecated and will be removed in 5.0.0. The use-case for this class comes from
* a pre-`phpstan/phpstan` and pre-`vimeo/psalm` ecosystem, in which type safety had to be mostly enforced
* at runtime: that is no longer necessary, now that you can safely verify your code to be correct, and use
* more generic types like `iterable<T>` instead.
* @deprecated this class has been deprecated and will be removed in 5.0.0. The use-case for this class comes from a
* pre-`phpstan/phpstan` and pre-`vimeo/psalm` ecosystem, in which type safety had to be mostly enforced at runtime:
* that is no longer necessary, now that you can safely verify your code to be correct, and use more generic types
* like `iterable<T>` instead.
*
* @extends AbstractCollection<UuidBuilderInterface>
*/
@@ -49,8 +49,7 @@ class BuilderCollection extends AbstractCollection
/**
* Re-constructs the object from its serialized form
*
* @param string $serialized The serialized PHP string to unserialize into
* a UuidInterface instance
* @param string $serialized The serialized PHP string to unserialize into a UuidInterface instance
*/
public function unserialize($serialized): void
{
@@ -72,7 +71,7 @@ class BuilderCollection extends AbstractCollection
function ($unserialized): bool {
/** @phpstan-ignore instanceof.alwaysTrue */
return $unserialized instanceof UuidBuilderInterface;
}
},
);
}
}
src/Builder/DefaultUuidBuilder.php
+1 -1
View File
@@ -17,7 +17,7 @@ namespace Ramsey\Uuid\Builder;
use Ramsey\Uuid\Rfc4122\UuidBuilder as Rfc4122UuidBuilder;
/**
* @deprecated Transition to {@see Rfc4122UuidBuilder}.
* @deprecated Please transition to {@see Rfc4122UuidBuilder}.
*
* @immutable
*/
src/Builder/DegradedUuidBuilder.php
+5 -12
View File
@@ -23,8 +23,7 @@ use Ramsey\Uuid\Rfc4122\Fields as Rfc4122Fields;
use Ramsey\Uuid\UuidInterface;
/**
* @deprecated DegradedUuid instances are no longer necessary to support 32-bit
* systems. Transition to {@see DefaultUuidBuilder}.
* @deprecated DegradedUuid instances are no longer necessary to support 32-bit systems. Please transition to {@see DefaultUuidBuilder}.
*
* @immutable
*/
@@ -33,10 +32,9 @@ class DegradedUuidBuilder implements UuidBuilderInterface
private TimeConverterInterface $timeConverter;
/**
* @param NumberConverterInterface $numberConverter The number converter to
* use when constructing the DegradedUuid
* @param TimeConverterInterface|null $timeConverter The time converter to use
* for converting timestamps extracted from a UUID to Unix timestamps
* @param NumberConverterInterface $numberConverter The number converter to use when constructing the DegradedUuid
* @param TimeConverterInterface|null $timeConverter The time converter to use for converting timestamps extracted
* from a UUID to Unix timestamps
*/
public function __construct(
private NumberConverterInterface $numberConverter,
@@ -55,11 +53,6 @@ class DegradedUuidBuilder implements UuidBuilderInterface
*/
public function build(CodecInterface $codec, string $bytes): UuidInterface
{
return new DegradedUuid(
new Rfc4122Fields($bytes),
$this->numberConverter,
$codec,
$this->timeConverter
);
return new DegradedUuid(new Rfc4122Fields($bytes), $this->numberConverter, $codec, $this->timeConverter);
}
}
src/Builder/FallbackBuilder.php
+3 -5
View File
@@ -20,8 +20,7 @@ use Ramsey\Uuid\Exception\UnableToBuildUuidException;
use Ramsey\Uuid\UuidInterface;
/**
* FallbackBuilder builds a UUID by stepping through a list of UUID builders
* until a UUID can be constructed without exceptions
* FallbackBuilder builds a UUID by stepping through a list of UUID builders until a UUID can be constructed without exceptions
*
* @immutable
*/
@@ -35,8 +34,7 @@ class FallbackBuilder implements UuidBuilderInterface
}
/**
* Builds and returns a UuidInterface instance using the first builder that
* succeeds
* Builds and returns a UuidInterface instance using the first builder that succeeds
*
* @param CodecInterface $codec The codec to use for building this instance
* @param string $bytes The byte string from which to construct a UUID
@@ -60,7 +58,7 @@ class FallbackBuilder implements UuidBuilderInterface
throw new BuilderNotFoundException(
'Could not find a suitable builder for the provided codec and fields',
0,
$lastBuilderException
$lastBuilderException,
);
}
}
src/Builder/UuidBuilderInterface.php
+1 -2
View File
@@ -30,8 +30,7 @@ interface UuidBuilderInterface
* @param CodecInterface $codec The codec to use for building this 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
* @return UuidInterface Implementations may choose to return more specific instances of UUIDs that implement UuidInterface
*/
public function build(CodecInterface $codec, string $bytes): UuidInterface;
}
src/Codec/CodecInterface.php
+6 -12
View File
@@ -26,8 +26,7 @@ interface CodecInterface
/**
* Returns a hexadecimal string representation of a UuidInterface
*
* @param UuidInterface $uuid The UUID for which to create a hexadecimal
* string representation
* @param UuidInterface $uuid The UUID for which to create a hexadecimal string representation
*
* @return non-empty-string Hexadecimal string representation of a UUID
*/
@@ -36,8 +35,7 @@ interface CodecInterface
/**
* Returns a binary string representation of a UuidInterface
*
* @param UuidInterface $uuid The UUID for which to create a binary string
* representation
* @param UuidInterface $uuid The UUID for which to create a binary string representation
*
* @return non-empty-string Binary string representation of a UUID
*/
@@ -46,22 +44,18 @@ interface CodecInterface
/**
* Returns a UuidInterface derived from a hexadecimal string representation
*
* @param string $encodedUuid The hexadecimal string representation to
* convert into a UuidInterface instance
* @param string $encodedUuid The hexadecimal string representation to convert into a UuidInterface instance
*
* @return UuidInterface An instance of a UUID decoded from a hexadecimal
* string representation
* @return UuidInterface An instance of a UUID decoded from a hexadecimal string representation
*/
public function decode(string $encodedUuid): UuidInterface;
/**
* Returns a UuidInterface derived from a binary string representation
*
* @param string $bytes The binary string representation to convert into a
* UuidInterface instance
* @param string $bytes The binary string representation to convert into a UuidInterface instance
*
* @return UuidInterface An instance of a UUID decoded from a binary string
* representation
* @return UuidInterface An instance of a UUID decoded from a binary string representation
*/
public function decodeBytes(string $bytes): UuidInterface;
}
src/Codec/GuidStringCodec.php
+2 -3
View File
@@ -59,7 +59,7 @@ class GuidStringCodec extends StringCodec
public function decodeBytes(string $bytes): UuidInterface
{
// Specifically call parent::decode to preserve correct byte order
// Call parent::decode() to preserve the correct byte order.
return parent::decode(bin2hex($bytes));
}
@@ -69,8 +69,7 @@ class GuidStringCodec extends StringCodec
private function swapBytes(string $bytes): string
{
return $bytes[3] . $bytes[2] . $bytes[1] . $bytes[0]
. $bytes[5] . $bytes[4]
. $bytes[7] . $bytes[6]
. $bytes[5] . $bytes[4] . $bytes[7] . $bytes[6]
. substr($bytes, 8);
}
}
src/Codec/OrderedTimeCodec.php
+16 -27
View File
@@ -24,20 +24,18 @@ use function strlen;
use function substr;
/**
* OrderedTimeCodec encodes and decodes a UUID, optimizing the byte order for
* more efficient storage
* OrderedTimeCodec encodes and decodes a UUID, optimizing the byte order for more efficient storage
*
* For binary representations of version 1 UUID, this codec may be used to
* reorganize the time fields, making the UUID closer to sequential when storing
* the bytes. According to Percona, this optimization can improve database
* INSERTs and SELECTs using the UUID column as a key.
* For binary representations of version 1 UUID, this codec may be used to reorganize the time fields, making the UUID
* closer to sequential when storing the bytes. According to Percona, this optimization can improve database INSERT and
* SELECT statements using the UUID column as a key.
*
* The string representation of the UUID will remain unchanged. Only the binary
* representation is reordered.
* The string representation of the UUID will remain unchanged. Only the binary representation is reordered.
*
* **PLEASE NOTE:** Binary representations of UUIDs encoded with this codec must
* be decoded with this codec. Decoding using another codec can result in
* malformed UUIDs.
* PLEASE NOTE: Binary representations of UUIDs encoded with this codec must be decoded with this codec. Decoding using
* another codec can result in malformed UUIDs.
*
* @deprecated Please migrate to {@link https://uuid.ramsey.dev/en/stable/rfc4122/version6.html Version 6, reordered time-based UUIDs}.
*
* @link https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/ Storing UUID Values in MySQL
*
@@ -46,8 +44,7 @@ use function substr;
class OrderedTimeCodec extends StringCodec
{
/**
* Returns a binary string representation of a UUID, with the timestamp
* fields rearranged for optimized storage
* Returns a binary string representation of a UUID, with the timestamp fields rearranged for optimized storage
*
* @return non-empty-string
*/
@@ -57,22 +54,18 @@ class OrderedTimeCodec extends StringCodec
!($uuid->getFields() instanceof Rfc4122FieldsInterface)
|| $uuid->getFields()->getVersion() !== Uuid::UUID_TYPE_TIME
) {
throw new InvalidArgumentException(
'Expected RFC 4122 version 1 (time-based) UUID'
);
throw new InvalidArgumentException('Expected version 1 (time-based) UUID');
}
$bytes = $uuid->getFields()->getBytes();
return $bytes[6] . $bytes[7]
. $bytes[4] . $bytes[5]
return $bytes[6] . $bytes[7] . $bytes[4] . $bytes[5]
. $bytes[0] . $bytes[1] . $bytes[2] . $bytes[3]
. substr($bytes, 8);
}
/**
* Returns a UuidInterface derived from an ordered-time binary string
* representation
* Returns a UuidInterface derived from an ordered-time binary string representation
*
* @throws InvalidArgumentException if $bytes is an invalid length
*
@@ -81,15 +74,12 @@ class OrderedTimeCodec extends StringCodec
public function decodeBytes(string $bytes): UuidInterface
{
if (strlen($bytes) !== 16) {
throw new InvalidArgumentException(
'$bytes string should contain 16 characters.'
);
throw new InvalidArgumentException('$bytes string should contain 16 characters.');
}
// Rearrange the bytes to their original order.
$rearrangedBytes = $bytes[4] . $bytes[5] . $bytes[6] . $bytes[7]
. $bytes[2] . $bytes[3]
. $bytes[0] . $bytes[1]
. $bytes[2] . $bytes[3] . $bytes[0] . $bytes[1]
. substr($bytes, 8);
$uuid = parent::decodeBytes($rearrangedBytes);
@@ -99,8 +89,7 @@ class OrderedTimeCodec extends StringCodec
|| $uuid->getFields()->getVersion() !== Uuid::UUID_TYPE_TIME
) {
throw new UnsupportedOperationException(
'Attempting to decode a non-time-based UUID using '
. 'OrderedTimeCodec'
'Attempting to decode a non-time-based UUID using OrderedTimeCodec',
);
}
src/Codec/StringCodec.php
+4 -14
View File
@@ -29,9 +29,7 @@ use function strlen;
use function substr;
/**
* StringCodec encodes and decodes RFC 4122 UUIDs
*
* @link http://tools.ietf.org/html/rfc4122
* StringCodec encodes and decodes RFC 9562 (formerly RFC 4122) UUIDs
*
* @immutable
*/
@@ -83,9 +81,7 @@ class StringCodec implements CodecInterface
public function decodeBytes(string $bytes): UuidInterface
{
if (strlen($bytes) !== 16) {
throw new InvalidArgumentException(
'$bytes string should contain 16 characters.'
);
throw new InvalidArgumentException('$bytes string should contain 16 characters.');
}
return $this->builder->build($this, $bytes);
@@ -104,11 +100,7 @@ class StringCodec implements CodecInterface
*/
protected function getBytes(string $encodedUuid): string
{
$parsedUuid = str_replace(
['urn:', 'uuid:', 'URN:', 'UUID:', '{', '}', '-'],
'',
$encodedUuid
);
$parsedUuid = str_replace(['urn:', 'uuid:', 'URN:', 'UUID:', '{', '}', '-'], '', $encodedUuid);
$components = [
substr($parsedUuid, 0, 8),
@@ -119,9 +111,7 @@ class StringCodec implements CodecInterface
];
if (!Uuid::isValid(implode('-', $components))) {
throw new InvalidUuidStringException(
'Invalid UUID string: ' . $encodedUuid
);
throw new InvalidUuidStringException('Invalid UUID string: ' . $encodedUuid);
}
return (string) hex2bin($parsedUuid);
src/Codec/TimestampFirstCombCodec.php
+10 -13
View File
@@ -23,28 +23,28 @@ use function substr;
use function substr_replace;
/**
* TimestampFirstCombCodec encodes and decodes COMBs, with the timestamp as the
* first 48 bits
* TimestampFirstCombCodec encodes and decodes COMBs, with the timestamp as the first 48 bits
*
* In contrast with the TimestampLastCombCodec, the TimestampFirstCombCodec
* adds the timestamp to the first 48 bits of the COMB. To generate a
* timestamp-first COMB, set the TimestampFirstCombCodec as the codec, along
* with the CombGenerator as the random generator.
* In contrast with the TimestampLastCombCodec, the TimestampFirstCombCodec adds the timestamp to the first 48 bits of
* the COMB. To generate a timestamp-first COMB, set the TimestampFirstCombCodec as the codec, along with the
* CombGenerator as the random generator.
*
* ``` php
* ```
* $factory = new UuidFactory();
*
* $factory->setCodec(new TimestampFirstCombCodec($factory->getUuidBuilder()));
*
* $factory->setRandomGenerator(new CombGenerator(
* $factory->getRandomGenerator(),
* $factory->getNumberConverter()
* $factory->getNumberConverter(),
* ));
*
* $timestampFirstComb = $factory->uuid4();
* ```
*
* @link https://www.informit.com/articles/printerfriendly/25862 The Cost of GUIDs as Primary Keys
* @deprecated Please migrate to {@link https://uuid.ramsey.dev/en/stable/rfc4122/version7.html Version 7, Unix Epoch Time UUIDs}.
*
* @link https://web.archive.org/web/20240118030355/https://www.informit.com/articles/printerfriendly/25862 The Cost of GUIDs as Primary Keys
*
* @immutable
*/
@@ -101,9 +101,6 @@ class TimestampFirstCombCodec extends StringCodec
$first48Bits = substr($bytes, 0, 6);
$last48Bits = substr($bytes, -6);
$bytes = substr_replace($bytes, $last48Bits, 0, 6);
$bytes = substr_replace($bytes, $first48Bits, -6);
return $bytes;
return substr_replace(substr_replace($bytes, $last48Bits, 0, 6), $first48Bits, -6);
}
}
src/Codec/TimestampLastCombCodec.php
+10 -13
View File
@@ -15,34 +15,31 @@ declare(strict_types=1);
namespace Ramsey\Uuid\Codec;
/**
* TimestampLastCombCodec encodes and decodes COMBs, with the timestamp as the
* last 48 bits
* TimestampLastCombCodec encodes and decodes COMBs, with the timestamp as the last 48 bits
*
* The CombGenerator when used with the StringCodec (and, by proxy, the
* TimestampLastCombCodec) adds the timestamp to the last 48 bits of the COMB.
* The TimestampLastCombCodec is provided for the sake of consistency. In
* practice, it is identical to the standard StringCodec but, it may be used
* with the CombGenerator for additional context when reading code.
* The CombGenerator when used with the StringCodec (and, by proxy, the TimestampLastCombCodec) adds the timestamp to
* the last 48 bits of the COMB. The TimestampLastCombCodec is provided for the sake of consistency. In practice, it is
* identical to the standard StringCodec, but it may be used with the CombGenerator for additional context when reading
* code.
*
* Consider the following code. By default, the codec used by UuidFactory is the
* StringCodec, but here, we explicitly set the TimestampLastCombCodec. It is
* redundant, but it is clear that we intend this COMB to be generated with the
* Consider the following code. By default, the codec used by UuidFactory is the StringCodec, but here, we explicitly
* set the TimestampLastCombCodec. It is redundant, but it is clear that we intend this COMB to be generated with the
* timestamp appearing at the end.
*
* ``` php
* ```
* $factory = new UuidFactory();
*
* $factory->setCodec(new TimestampLastCombCodec($factory->getUuidBuilder()));
*
* $factory->setRandomGenerator(new CombGenerator(
* $factory->getRandomGenerator(),
* $factory->getNumberConverter()
* $factory->getNumberConverter(),
* ));
*
* $timestampLastComb = $factory->uuid4();
* ```
*
* @link https://www.informit.com/articles/printerfriendly/25862 The Cost of GUIDs as Primary Keys
* @deprecated Please use {@see StringCodec} instead.
*
* @immutable
*/
src/Converter/Number/BigNumberConverter.php
+3 -3
View File
@@ -18,10 +18,10 @@ use Ramsey\Uuid\Converter\NumberConverterInterface;
use Ramsey\Uuid\Math\BrickMathCalculator;
/**
* Previously used to integrate moontoast/math as a bignum arithmetic library,
* BigNumberConverter is deprecated in favor of GenericNumberConverter
* Previously used to integrate moontoast/math as a bignum arithmetic library, BigNumberConverter is deprecated in favor
* of GenericNumberConverter
*
* @deprecated Transition to {@see GenericNumberConverter}.
* @deprecated Please transition to {@see GenericNumberConverter}.
*
* @immutable
*/
src/Converter/Number/DegradedNumberConverter.php
+2 -2
View File
@@ -15,8 +15,8 @@ declare(strict_types=1);
namespace Ramsey\Uuid\Converter\Number;
/**
* @deprecated DegradedNumberConverter is no longer necessary for converting
* numbers on 32-bit systems. Transition to {@see GenericNumberConverter}.
* @deprecated DegradedNumberConverter is no longer necessary for converting numbers on 32-bit systems. Please
* transition to {@see GenericNumberConverter}.
*
* @immutable
*/
src/Converter/Number/GenericNumberConverter.php
+1 -2
View File
@@ -19,8 +19,7 @@ use Ramsey\Uuid\Math\CalculatorInterface;
use Ramsey\Uuid\Type\Integer as IntegerObject;
/**
* GenericNumberConverter uses the provided calculator to convert decimal
* numbers to and from hexadecimal values
* GenericNumberConverter uses the provided calculator to convert decimal numbers to and from hexadecimal values
*
* @immutable
*/
src/Converter/NumberConverterInterface.php
+7 -11
View File
@@ -15,19 +15,17 @@ declare(strict_types=1);
namespace Ramsey\Uuid\Converter;
/**
* A number converter converts UUIDs from hexadecimal characters into
* representations of integers and vice versa
* A number converter converts UUIDs from hexadecimal characters into representations of integers and vice versa
*
* @immutable
*/
interface NumberConverterInterface
{
/**
* Converts a hexadecimal number into a string integer representation of
* the number
* Converts a hexadecimal number into a string integer representation of the number
*
* The integer representation returned is a string representation of the
* integer to accommodate unsigned integers greater than PHP_INT_MAX.
* The integer representation returned is a string representation of the integer to accommodate unsigned integers
* that are greater than `PHP_INT_MAX`.
*
* @param string $hex The hexadecimal string representation to convert
*
@@ -36,12 +34,10 @@ interface NumberConverterInterface
public function fromHex(string $hex): string;
/**
* Converts a string integer representation into a hexadecimal string
* representation of the number
* Converts a string integer representation into a hexadecimal string representation of the number
*
* @param string $number A string integer representation to convert; this
* must be a numeric string to accommodate unsigned integers greater
* than PHP_INT_MAX.
* @param string $number A string integer representation to convert; this must be a numeric string to accommodate
* unsigned integers that are greater than `PHP_INT_MAX`.
*
* @return non-empty-string Hexadecimal string
*/
src/Converter/Time/BigNumberTimeConverter.php
+3 -3
View File
@@ -20,10 +20,10 @@ use Ramsey\Uuid\Type\Hexadecimal;
use Ramsey\Uuid\Type\Time;
/**
* Previously used to integrate moontoast/math as a bignum arithmetic library,
* BigNumberTimeConverter is deprecated in favor of GenericTimeConverter
* Previously used to integrate moontoast/math as a bignum arithmetic library, BigNumberTimeConverter is deprecated in
* favor of GenericTimeConverter
*
* @deprecated Transition to {@see GenericTimeConverter}.
* @deprecated Please transition to {@see GenericTimeConverter}.
*
* @immutable
*/
src/Converter/Time/DegradedTimeConverter.php
+2 -2
View File
@@ -15,8 +15,8 @@ declare(strict_types=1);
namespace Ramsey\Uuid\Converter\Time;
/**
* @deprecated DegradedTimeConverter is no longer necessary for converting
* time on 32-bit systems. Transition to {@see GenericTimeConverter}.
* @deprecated DegradedTimeConverter is no longer necessary for converting time on 32-bit systems. Please transition to
* {@see GenericTimeConverter}.
*
* @immutable
*/
src/Converter/Time/GenericTimeConverter.php
+13 -30
View File
@@ -27,16 +27,14 @@ use function str_pad;
use const STR_PAD_LEFT;
/**
* GenericTimeConverter uses the provided calculator to calculate and convert
* time values
* GenericTimeConverter uses the provided calculator to calculate and convert time values
*
* @immutable
*/
class GenericTimeConverter implements TimeConverterInterface
{
/**
* The number of 100-nanosecond intervals from the Gregorian calendar epoch
* to the Unix epoch.
* The number of 100-nanosecond intervals from the Gregorian calendar epoch to the Unix epoch.
*/
private const GREGORIAN_TO_UNIX_INTERVALS = '122192928000000000';
@@ -61,46 +59,31 @@ class GenericTimeConverter implements TimeConverterInterface
// Convert the seconds into a count of 100-nanosecond intervals.
$sec = $this->calculator->multiply(
$timestamp->getSeconds(),
new IntegerObject(self::SECOND_INTERVALS)
new IntegerObject(self::SECOND_INTERVALS),
);
// Convert the microseconds into a count of 100-nanosecond intervals.
$usec = $this->calculator->multiply(
$timestamp->getMicroseconds(),
new IntegerObject(self::MICROSECOND_INTERVALS)
new IntegerObject(self::MICROSECOND_INTERVALS),
);
// Combine the seconds and microseconds intervals and add the count of
// 100-nanosecond intervals from the Gregorian calendar epoch to the
// Unix epoch. This gives us the correct count of 100-nanosecond
// intervals since the Gregorian calendar epoch for the given seconds
// and microseconds.
// Combine the intervals of seconds and microseconds and add the count of 100-nanosecond intervals from the
// Gregorian calendar epoch to the Unix epoch. This gives us the correct count of 100-nanosecond intervals since
// the Gregorian calendar epoch for the given seconds and microseconds.
/** @var IntegerObject $uuidTime */
$uuidTime = $this->calculator->add(
$sec,
$usec,
new IntegerObject(self::GREGORIAN_TO_UNIX_INTERVALS)
);
$uuidTime = $this->calculator->add($sec, $usec, new IntegerObject(self::GREGORIAN_TO_UNIX_INTERVALS));
$uuidTimeHex = str_pad(
$this->calculator->toHexadecimal($uuidTime)->toString(),
16,
'0',
STR_PAD_LEFT
);
return new Hexadecimal($uuidTimeHex);
return new Hexadecimal(str_pad($this->calculator->toHexadecimal($uuidTime)->toString(), 16, '0', STR_PAD_LEFT));
}
public function convertTime(Hexadecimal $uuidTimestamp): Time
{
// From the total, subtract the number of 100-nanosecond intervals from
// the Gregorian calendar epoch to the Unix epoch. This gives us the
// number of 100-nanosecond intervals from the Unix epoch, which also
// includes the microtime.
// From the total, subtract the number of 100-nanosecond intervals from the Gregorian calendar epoch to the Unix
// epoch. This gives us the number of 100-nanosecond intervals from the Unix epoch, which also includes the microtime.
$epochNanoseconds = $this->calculator->subtract(
$this->calculator->toInteger($uuidTimestamp),
new IntegerObject(self::GREGORIAN_TO_UNIX_INTERVALS)
new IntegerObject(self::GREGORIAN_TO_UNIX_INTERVALS),
);
// Convert the 100-nanosecond intervals into seconds and microseconds.
@@ -108,7 +91,7 @@ class GenericTimeConverter implements TimeConverterInterface
RoundingMode::HALF_UP,
6,
$epochNanoseconds,
new IntegerObject(self::SECOND_INTERVALS)
new IntegerObject(self::SECOND_INTERVALS),
);
$split = explode('.', (string) $unixTimestamp, 2);
src/Converter/Time/PhpTimeConverter.php
+16 -24
View File
@@ -34,24 +34,22 @@ use const STR_PAD_LEFT;
use const STR_PAD_RIGHT;
/**
* PhpTimeConverter uses built-in PHP functions and standard math operations
* available to the PHP programming language to provide facilities for
* converting parts of time into representations that may be used in UUIDs
* PhpTimeConverter uses built-in PHP functions and standard math operations available to the PHP programming language
* to provide facilities for converting parts of time into representations that may be used in UUIDs
*
* @immutable
*/
class PhpTimeConverter implements TimeConverterInterface
{
/**
* The number of 100-nanosecond intervals from the Gregorian calendar epoch
* to the Unix epoch.
* The number of 100-nanosecond intervals from the Gregorian calendar epoch to the Unix epoch.
*/
private const GREGORIAN_TO_UNIX_INTERVALS = 0x01b21dd213814000;
/**
* The number of 100-nanosecond intervals in one second.
*/
private const SECOND_INTERVALS = 10000000;
private const SECOND_INTERVALS = 10_000_000;
/**
* The number of 100-nanosecond intervals in one microsecond.
@@ -64,7 +62,7 @@ class PhpTimeConverter implements TimeConverterInterface
public function __construct(
?CalculatorInterface $calculator = null,
?TimeConverterInterface $fallbackConverter = null
?TimeConverterInterface $fallbackConverter = null,
) {
if ($calculator === null) {
$calculator = new BrickMathCalculator();
@@ -84,8 +82,8 @@ class PhpTimeConverter implements TimeConverterInterface
$seconds = new IntegerObject($seconds);
$microseconds = new IntegerObject($microseconds);
// Calculate the count of 100-nanosecond intervals since the Gregorian
// calendar epoch for the given seconds and microseconds.
// Calculate the count of 100-nanosecond intervals since the Gregorian calendar epoch
// for the given seconds and microseconds.
$uuidTime = ((int) $seconds->toString() * self::SECOND_INTERVALS)
+ ((int) $microseconds->toString() * self::MICROSECOND_INTERVALS)
+ self::GREGORIAN_TO_UNIX_INTERVALS;
@@ -96,7 +94,7 @@ class PhpTimeConverter implements TimeConverterInterface
if (!is_int($uuidTime)) {
return $this->fallbackConverter->calculateTime(
$seconds->toString(),
$microseconds->toString()
$microseconds->toString(),
);
}
@@ -109,8 +107,7 @@ class PhpTimeConverter implements TimeConverterInterface
// Convert the 100-nanosecond intervals into seconds and microseconds.
$splitTime = $this->splitTime(
((int) $timestamp->toString() - self::GREGORIAN_TO_UNIX_INTERVALS)
/ self::SECOND_INTERVALS
((int) $timestamp->toString() - self::GREGORIAN_TO_UNIX_INTERVALS) / self::SECOND_INTERVALS,
);
if (count($splitTime) === 0) {
@@ -121,7 +118,7 @@ class PhpTimeConverter implements TimeConverterInterface
}
/**
* @param float|int $time The time to split into seconds and microseconds
* @param float | int $time The time to split into seconds and microseconds
*
* @return string[]
*/
@@ -129,24 +126,19 @@ class PhpTimeConverter implements TimeConverterInterface
{
$split = explode('.', (string) $time, 2);
// If the $time value is a float but $split only has 1 element, then the
// float math was rounded up to the next second, so we want to return
// an empty array to allow use of the fallback converter.
// If the $time value is a float but $split only has 1 element, then the float math was rounded up to the next
// second, so we want to return an empty array to allow use of the fallback converter.
if (is_float($time) && count($split) === 1) {
return [];
}
if (count($split) === 1) {
return [
'sec' => $split[0],
'usec' => '0',
];
return ['sec' => $split[0], 'usec' => '0'];
}
// If the microseconds are less than six characters AND the length of
// the number is greater than or equal to the PHP precision, then it's
// possible that we lost some precision for the microseconds. Return an
// empty array, so that we can choose to use the fallback converter.
// If the microseconds are less than six characters AND the length of the number is greater than or equal to the
// PHP precision, then it's possible that we lost some precision for the microseconds. Return an empty array so
// that we can choose to use the fallback converter.
if (strlen($split[1]) < 6 && strlen((string) $time) >= $this->phpPrecision) {
return [];
}
src/Converter/Time/UnixTimeConverter.php
+6 -17
View File
@@ -27,8 +27,8 @@ use function str_pad;
use const STR_PAD_LEFT;
/**
* UnixTimeConverter converts Unix Epoch timestamps to/from hexadecimal values
* consisting of milliseconds elapsed since the Unix Epoch
* UnixTimeConverter converts Unix Epoch timestamps to/from hexadecimal values consisting of milliseconds elapsed since
* the Unix Epoch
*
* @immutable
*/
@@ -45,13 +45,9 @@ class UnixTimeConverter implements TimeConverterInterface
$timestamp = new Time($seconds, $microseconds);
// Convert the seconds into milliseconds.
$sec = $this->calculator->multiply(
$timestamp->getSeconds(),
new IntegerObject(self::MILLISECONDS),
);
$sec = $this->calculator->multiply($timestamp->getSeconds(), new IntegerObject(self::MILLISECONDS));
// Convert the microseconds into milliseconds; the scale is zero because
// we need to discard the fractional part.
// Convert the microseconds into milliseconds; the scale is zero because we need to discard the fractional part.
$usec = $this->calculator->divide(
RoundingMode::DOWN, // Always round down to stay in the previous millisecond.
0,
@@ -62,14 +58,7 @@ class UnixTimeConverter implements TimeConverterInterface
/** @var IntegerObject $unixTime */
$unixTime = $this->calculator->add($sec, $usec);
$unixTimeHex = str_pad(
$this->calculator->toHexadecimal($unixTime)->toString(),
12,
'0',
STR_PAD_LEFT
);
return new Hexadecimal($unixTimeHex);
return new Hexadecimal(str_pad($this->calculator->toHexadecimal($unixTime)->toString(), 12, '0', STR_PAD_LEFT));
}
public function convertTime(Hexadecimal $uuidTimestamp): Time
@@ -80,7 +69,7 @@ class UnixTimeConverter implements TimeConverterInterface
RoundingMode::HALF_UP,
6,
$milliseconds,
new IntegerObject(self::MILLISECONDS)
new IntegerObject(self::MILLISECONDS),
);
$split = explode('.', (string) $unixTimestamp, 2);
src/Converter/TimeConverterInterface.php
+8 -13
View File
@@ -18,24 +18,20 @@ use Ramsey\Uuid\Type\Hexadecimal;
use Ramsey\Uuid\Type\Time;
/**
* A time converter converts timestamps into representations that may be used
* in UUIDs
* A time converter converts timestamps into representations that may be used in UUIDs
*
* @immutable
*/
interface TimeConverterInterface
{
/**
* Uses the provided seconds and micro-seconds to calculate the count of
* 100-nanosecond intervals since UTC 00:00:00.00, 15 October 1582, for
* RFC 4122 variant UUIDs
* Uses the provided seconds and micro-seconds to calculate the count of 100-nanosecond intervals since
* UTC 00:00:00.00, 15 October 1582, for RFC 9562 (formerly RFC 4122) variant UUIDs
*
* @link http://tools.ietf.org/html/rfc4122#section-4.2.2 RFC 4122, § 4.2.2: Generation Details
* @link https://www.rfc-editor.org/rfc/rfc9562#appendix-A RFC 9562, Appendix A. Test Vectors
*
* @param string $seconds A string representation of the number of seconds
* since the Unix epoch for the time to calculate
* @param string $microseconds A string representation of the micro-seconds
* associated with the time to calculate
* @param string $seconds A string representation of seconds since the Unix epoch for the time to calculate
* @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
*/
@@ -44,9 +40,8 @@ interface TimeConverterInterface
/**
* Converts a timestamp extracted from a UUID to a Unix timestamp
*
* @param Hexadecimal $uuidTimestamp A hexadecimal representation of a UUID
* timestamp; a UUID timestamp is a count of 100-nanosecond intervals
* since UTC 00:00:00.00, 15 October 1582.
* @param Hexadecimal $uuidTimestamp A hexadecimal representation of a UUID timestamp; a UUID timestamp is a count
* of 100-nanosecond intervals since UTC 00:00:00.00, 15 October 1582.
*
* @return Time An instance of {@see Time}
*/
src/DegradedUuid.php
+2 -2
View File
@@ -15,8 +15,8 @@ declare(strict_types=1);
namespace Ramsey\Uuid;
/**
* @deprecated DegradedUuid is no longer necessary to represent UUIDs on 32-bit
* systems. Transition typehints to {@see UuidInterface}.
* @deprecated DegradedUuid is no longer necessary to represent UUIDs on 32-bit systems.
* Transition any type declarations using this class to {@see UuidInterface}.
*
* @immutable
*/
src/DeprecatedUuidInterface.php
+18 -32
View File
@@ -25,114 +25,100 @@ use Ramsey\Uuid\Converter\NumberConverterInterface;
interface DeprecatedUuidInterface
{
/**
* @deprecated This method will be removed in 5.0.0. There is no alternative
* recommendation, so plan accordingly.
* @deprecated This method will be removed in 5.0.0. There is no alternative recommendation, so plan accordingly.
*/
public function getNumberConverter(): NumberConverterInterface;
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance.
*
* @return string[]
*/
public function getFieldsHex(): array;
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeqHiAndReserved()}.
*/
public function getClockSeqHiAndReservedHex(): string;
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeqLow()}.
*/
public function getClockSeqLowHex(): string;
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeq()}.
*/
public function getClockSequenceHex(): string;
/**
* @deprecated In ramsey/uuid version 5.0.0, this will be removed from the
* interface. It is available at {@see UuidV1::getDateTime()}.
* @deprecated In ramsey/uuid version 5.0.0, this will be removed from the interface. It is available at
* {@see UuidV1::getDateTime()}.
*/
public function getDateTime(): DateTimeInterface;
/**
* @deprecated This method will be removed in 5.0.0. There is no direct
* alternative, but the same information may be obtained by splitting
* in half the value returned by {@see UuidInterface::getHex()}.
* @deprecated This method will be removed in 5.0.0. There is no direct alternative, but the same information may be
* obtained by splitting in half the value returned by {@see UuidInterface::getHex()}.
*/
public function getLeastSignificantBitsHex(): string;
/**
* @deprecated This method will be removed in 5.0.0. There is no direct
* alternative, but the same information may be obtained by splitting
* in half the value returned by {@see UuidInterface::getHex()}.
* @deprecated This method will be removed in 5.0.0. There is no direct alternative, but the same information may be
* obtained by splitting in half the value returned by {@see UuidInterface::getHex()}.
*/
public function getMostSignificantBitsHex(): string;
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getNode()}.
*/
public function getNodeHex(): string;
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeHiAndVersion()}.
*/
public function getTimeHiAndVersionHex(): string;
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeLow()}.
*/
public function getTimeLowHex(): string;
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeMid()}.
*/
public function getTimeMidHex(): string;
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimestamp()}.
*/
public function getTimestampHex(): string;
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getVariant()}.
*/
public function getVariant(): ?int;
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getVersion()}.
*/
src/DeprecatedUuidMethodsTrait.php
+64 -98
View File
@@ -27,8 +27,7 @@ use function substr;
use const STR_PAD_LEFT;
/**
* This trait encapsulates deprecated methods for ramsey/uuid; this trait and
* its methods will be removed in ramsey/uuid 5.0.0.
* This trait encapsulates deprecated methods for ramsey/uuid; this trait and its methods will be removed in ramsey/uuid 5.0.0.
*
* @deprecated This trait and its methods will be removed in ramsey/uuid 5.0.0.
*
@@ -37,12 +36,10 @@ use const STR_PAD_LEFT;
trait DeprecatedUuidMethodsTrait
{
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeqHiAndReserved()}
* and use the arbitrary-precision math library of your choice to
* convert it to a string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeqHiAndReserved()} and use the arbitrary-precision math
* library of your choice to convert it to a string integer.
*/
public function getClockSeqHiAndReserved(): string
{
@@ -50,9 +47,8 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeqHiAndReserved()}.
*/
public function getClockSeqHiAndReservedHex(): string
@@ -61,12 +57,10 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeqLow()}
* and use the arbitrary-precision math library of your choice to
* convert it to a string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeqLow()} and use the arbitrary-precision math library of
* your choice to convert it to a string integer.
*/
public function getClockSeqLow(): string
{
@@ -74,9 +68,8 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeqLow()}.
*/
public function getClockSeqLowHex(): string
@@ -85,12 +78,10 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeq()}
* and use the arbitrary-precision math library of your choice to
* convert it to a string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeq()} and use the arbitrary-precision math library of
* your choice to convert it to a string integer.
*/
public function getClockSequence(): string
{
@@ -98,9 +89,8 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeq()}.
*/
public function getClockSequenceHex(): string
@@ -109,8 +99,7 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated This method will be removed in 5.0.0. There is no alternative
* recommendation, so plan accordingly.
* @deprecated This method will be removed in 5.0.0. There is no alternative recommendation, so plan accordingly.
*/
public function getNumberConverter(): NumberConverterInterface
{
@@ -118,8 +107,7 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated In ramsey/uuid version 5.0.0, this will be removed.
* It is available at {@see UuidV1::getDateTime()}.
* @deprecated In ramsey/uuid version 5.0.0, this will be removed. It is available at {@see UuidV1::getDateTime()}.
*
* @return DateTimeImmutable An immutable instance of DateTimeInterface
*
@@ -147,8 +135,7 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
*
* @return string[]
*/
@@ -165,9 +152,8 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated This method will be removed in 5.0.0. There is no direct
* alternative, but the same information may be obtained by splitting
* in half the value returned by {@see UuidInterface::getHex()}.
* @deprecated This method will be removed in 5.0.0. There is no direct alternative, but the same information may be
* obtained by splitting in half the value returned by {@see UuidInterface::getHex()}.
*/
public function getLeastSignificantBits(): string
{
@@ -177,9 +163,8 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated This method will be removed in 5.0.0. There is no direct
* alternative, but the same information may be obtained by splitting
* in half the value returned by {@see UuidInterface::getHex()}.
* @deprecated This method will be removed in 5.0.0. There is no direct alternative, but the same information may be
* obtained by splitting in half the value returned by {@see UuidInterface::getHex()}.
*/
public function getLeastSignificantBitsHex(): string
{
@@ -187,9 +172,8 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated This method will be removed in 5.0.0. There is no direct
* alternative, but the same information may be obtained by splitting
* in half the value returned by {@see UuidInterface::getHex()}.
* @deprecated This method will be removed in 5.0.0. There is no direct alternative, but the same information may be
* obtained by splitting in half the value returned by {@see UuidInterface::getHex()}.
*/
public function getMostSignificantBits(): string
{
@@ -199,9 +183,8 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated This method will be removed in 5.0.0. There is no direct
* alternative, but the same information may be obtained by splitting
* in half the value returned by {@see UuidInterface::getHex()}.
* @deprecated This method will be removed in 5.0.0. There is no direct alternative, but the same information may be
* obtained by splitting in half the value returned by {@see UuidInterface::getHex()}.
*/
public function getMostSignificantBitsHex(): string
{
@@ -209,12 +192,10 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getNode()} and use the
* arbitrary-precision math library of your choice to convert it to a
* string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getNode()} and use the arbitrary-precision math library of your
* choice to convert it to a string integer.
*/
public function getNode(): string
{
@@ -222,9 +203,8 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getNode()}.
*/
public function getNodeHex(): string
@@ -233,12 +213,10 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeHiAndVersion()}
* and use the arbitrary-precision math library of your choice to
* convert it to a string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeHiAndVersion()} and use the arbitrary-precision math
* library of your choice to convert it to a string integer.
*/
public function getTimeHiAndVersion(): string
{
@@ -246,9 +224,8 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeHiAndVersion()}.
*/
public function getTimeHiAndVersionHex(): string
@@ -257,12 +234,10 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeLow()} and use the
* arbitrary-precision math library of your choice to convert it to a
* string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeLow()} and use the arbitrary-precision math library of
* your choice to convert it to a string integer.
*/
public function getTimeLow(): string
{
@@ -270,9 +245,8 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeLow()}.
*/
public function getTimeLowHex(): string
@@ -281,12 +255,10 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeMid()} and use the
* arbitrary-precision math library of your choice to convert it to a
* string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeMid()} and use the arbitrary-precision math library of
* your choice to convert it to a string integer.
*/
public function getTimeMid(): string
{
@@ -294,9 +266,8 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeMid()}.
*/
public function getTimeMidHex(): string
@@ -305,12 +276,10 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimestamp()} and use
* the arbitrary-precision math library of your choice to convert it to
* a string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimestamp()} and use the arbitrary-precision math library of
* your choice to convert it to a string integer.
*/
public function getTimestamp(): string
{
@@ -322,9 +291,8 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimestamp()}.
*/
public function getTimestampHex(): string
@@ -337,9 +305,8 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getVariant()}.
*/
public function getVariant(): ?int
@@ -348,9 +315,8 @@ trait DeprecatedUuidMethodsTrait
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see \Ramsey\Uuid\Fields\FieldsInterface} instance.
* If it is a {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call
* {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getVersion()}.
*/
public function getVersion(): ?int
src/Exception/DceSecurityException.php
+1 -2
View File
@@ -17,8 +17,7 @@ namespace Ramsey\Uuid\Exception;
use RuntimeException as PhpRuntimeException;
/**
* Thrown to indicate an exception occurred while dealing with DCE Security
* (version 2) UUIDs
* Thrown to indicate an exception occurred while dealing with DCE Security (version 2) UUIDs
*/
class DceSecurityException extends PhpRuntimeException implements UuidExceptionInterface
{
src/Exception/InvalidUuidStringException.php
+2 -2
View File
@@ -17,8 +17,8 @@ namespace Ramsey\Uuid\Exception;
/**
* Thrown to indicate that the string received is not a valid UUID
*
* The InvalidArgumentException that this extends is the ramsey/uuid version
* of this exception. It exists in the same namespace as this class.
* The InvalidArgumentException that this extends is the ramsey/uuid version of this exception. It exists in the same
* namespace as this class.
*/
class InvalidUuidStringException extends InvalidArgumentException implements UuidExceptionInterface
{
src/Exception/NameException.php
+1 -2
View File
@@ -17,8 +17,7 @@ namespace Ramsey\Uuid\Exception;
use RuntimeException as PhpRuntimeException;
/**
* Thrown to indicate that an error occurred while attempting to hash a
* namespace and name
* Thrown to indicate that an error occurred while attempting to hash a namespace and name
*/
class NameException extends PhpRuntimeException implements UuidExceptionInterface
{
src/Exception/RandomSourceException.php
+2 -2
View File
@@ -19,8 +19,8 @@ use RuntimeException as PhpRuntimeException;
/**
* Thrown to indicate that the source of random data encountered an error
*
* This exception is used mostly to indicate that random_bytes() or random_int()
* threw an exception. However, it may be used for other sources of random data.
* This exception is used mostly to indicate that random_bytes() or random_int() threw an exception. However, it may be
* used for other sources of random data.
*/
class RandomSourceException extends PhpRuntimeException implements UuidExceptionInterface
{
src/FeatureSet.php
+9 -24
View File
@@ -57,8 +57,7 @@ use const PHP_INT_SIZE;
/**
* FeatureSet detects and exposes available features in the current environment
*
* A feature set is used by UuidFactory to determine the available features and
* capabilities of the environment.
* A feature set is used by UuidFactory to determine the available features and capabilities of the environment.
*/
class FeatureSet
{
@@ -78,13 +77,10 @@ class FeatureSet
/**
* @param bool $useGuids True build UUIDs using the GuidStringCodec
* @param bool $force32Bit True to force the use of 32-bit functionality
* (primarily for testing purposes)
* @param bool $force32Bit True to force the use of 32-bit functionality (primarily for testing purposes)
* @param bool $forceNoBigNumber (obsolete)
* @param bool $ignoreSystemNode True to disable attempts to check for the
* system node ID (primarily for testing purposes)
* @param bool $enablePecl True to enable the use of the PeclUuidTimeGenerator
* to generate version 1 UUIDs
* @param bool $ignoreSystemNode True to disable attempts to check for the system node ID (primarily for testing purposes)
* @param bool $enablePecl True to enable the use of the PeclUuidTimeGenerator to generate version 1 UUIDs
*
* @phpstan-ignore constructor.unusedParameter ($forceNoBigNumber is deprecated)
*/
@@ -93,7 +89,7 @@ class FeatureSet
private bool $force32Bit = false,
bool $forceNoBigNumber = false,
private bool $ignoreSystemNode = false,
private bool $enablePecl = false
private bool $enablePecl = false,
) {
$this->randomGenerator = $this->buildRandomGenerator();
$this->setCalculator(new BrickMathCalculator());
@@ -274,13 +270,9 @@ class FeatureSet
* Returns a DCE Security generator configured for this environment
*/
private function buildDceSecurityGenerator(
DceSecurityProviderInterface $dceSecurityProvider
DceSecurityProviderInterface $dceSecurityProvider,
): DceSecurityGeneratorInterface {
return new DceSecurityGenerator(
$this->numberConverter,
$this->timeGenerator,
$dceSecurityProvider
);
return new DceSecurityGenerator($this->numberConverter, $this->timeGenerator, $dceSecurityProvider);
}
/**
@@ -292,10 +284,7 @@ class FeatureSet
return new RandomNodeProvider();
}
return new FallbackNodeProvider([
new SystemNodeProvider(),
new RandomNodeProvider(),
]);
return new FallbackNodeProvider([new SystemNodeProvider(), new RandomNodeProvider()]);
}
/**
@@ -330,11 +319,7 @@ class FeatureSet
return new PeclUuidTimeGenerator();
}
return (new TimeGeneratorFactory(
$this->nodeProvider,
$this->timeConverter,
$timeProvider
))->getGenerator();
return (new TimeGeneratorFactory($this->nodeProvider, $this->timeConverter, $timeProvider))->getGenerator();
}
/**
src/Fields/FieldsInterface.php
+2 -3
View File
@@ -17,9 +17,8 @@ namespace Ramsey\Uuid\Fields;
use Serializable;
/**
* UUIDs consist of unsigned integers, the bytes of which are separated
* into fields and arranged in a particular layout defined by the specification
* for the variant
* UUIDs consist of unsigned integers, the bytes of which are separated into fields and arranged in a particular layout
* defined by the specification for the variant
*
* @immutable
*/
src/Fields/SerializableFieldsTrait.php
+1 -1
View File
@@ -38,7 +38,7 @@ trait SerializableFieldsTrait
abstract public function getBytes(): string;
/**
* Returns a string representation of object
* Returns a string representation of the object
*/
public function serialize(): string
{
src/Generator/CombGenerator.php
+15 -24
View File
@@ -29,33 +29,32 @@ use const STR_PAD_LEFT;
/**
* CombGenerator generates COMBs (combined UUID/timestamp)
*
* The CombGenerator, when used with the StringCodec (and, by proxy, the
* TimestampLastCombCodec) or the TimestampFirstCombCodec, combines the current
* timestamp with a UUID (hence the name "COMB"). The timestamp either appears
* as the first or last 48 bits of the COMB, depending on the codec used.
* The CombGenerator, when used with the StringCodec (and, by proxy, the TimestampLastCombCodec) or the
* TimestampFirstCombCodec, combines the current timestamp with a UUID (hence the name "COMB"). The timestamp either
* appears as the first or last 48 bits of the COMB, depending on the codec used.
*
* By default, COMBs will have the timestamp set as the last 48 bits of the
* identifier.
* By default, COMBs will have the timestamp set as the last 48 bits of the identifier.
*
* ``` php
* ```
* $factory = new UuidFactory();
*
* $factory->setRandomGenerator(new CombGenerator(
* $factory->getRandomGenerator(),
* $factory->getNumberConverter()
* $factory->getNumberConverter(),
* ));
*
* $comb = $factory->uuid4();
* ```
*
* To generate a COMB with the timestamp as the first 48 bits, set the
* TimestampFirstCombCodec as the codec.
* To generate a COMB with the timestamp as the first 48 bits, set the TimestampFirstCombCodec as the codec.
*
* ``` php
* ```
* $factory->setCodec(new TimestampFirstCombCodec($factory->getUuidBuilder()));
* ```
*
* @link https://www.informit.com/articles/printerfriendly/25862 The Cost of GUIDs as Primary Keys
* @deprecated Please migrate to {@link https://uuid.ramsey.dev/en/stable/rfc4122/version7.html Version 7, Unix Epoch Time UUIDs}.
*
* @link https://web.archive.org/web/20240118030355/https://www.informit.com/articles/printerfriendly/25862 The Cost of GUIDs as Primary Keys
*/
class CombGenerator implements RandomGeneratorInterface
{
@@ -68,8 +67,7 @@ class CombGenerator implements RandomGeneratorInterface
}
/**
* @throws InvalidArgumentException if $length is not a positive integer
* greater than or equal to CombGenerator::TIMESTAMP_BYTES
* @throws InvalidArgumentException if $length is not a positive integer greater than or equal to CombGenerator::TIMESTAMP_BYTES
*
* @inheritDoc
*/
@@ -96,21 +94,14 @@ class CombGenerator implements RandomGeneratorInterface
$this->numberConverter->toHex($this->timestamp()),
self::TIMESTAMP_BYTES * 2,
'0',
STR_PAD_LEFT
STR_PAD_LEFT,
);
return (string) hex2bin(
str_pad(
bin2hex($hash),
$length - self::TIMESTAMP_BYTES,
'0'
)
. $lsbTime
);
return (string) hex2bin(str_pad(bin2hex($hash), $length - self::TIMESTAMP_BYTES, '0') . $lsbTime);
}
/**
* Returns current timestamp a string integer, precise to 0.00001 seconds
* Returns the current timestamp as a string integer, precise to 0.00001 seconds
*/
private function timestamp(): string
{
src/Generator/DceSecurityGenerator.php
+11 -19
View File
@@ -31,8 +31,8 @@ use function substr_replace;
use const STR_PAD_LEFT;
/**
* DceSecurityGenerator generates strings of binary data based on a local
* domain, local identifier, node ID, clock sequence, and the current time
* DceSecurityGenerator generates strings of binary data based on a local domain, local identifier, node ID, clock
* sequence, and the current time
*/
class DceSecurityGenerator implements DceSecurityGeneratorInterface
{
@@ -55,7 +55,7 @@ class DceSecurityGenerator implements DceSecurityGeneratorInterface
public function __construct(
private NumberConverterInterface $numberConverter,
private TimeGeneratorInterface $timeGenerator,
private DceSecurityProviderInterface $dceSecurityProvider
private DceSecurityProviderInterface $dceSecurityProvider,
) {
}
@@ -63,32 +63,26 @@ class DceSecurityGenerator implements DceSecurityGeneratorInterface
int $localDomain,
?IntegerObject $localIdentifier = null,
?Hexadecimal $node = null,
?int $clockSeq = null
?int $clockSeq = null,
): string {
if (!in_array($localDomain, self::DOMAINS)) {
throw new DceSecurityException(
'Local domain must be a valid DCE Security domain'
);
throw new DceSecurityException('Local domain must be a valid DCE Security domain');
}
if ($localIdentifier && $localIdentifier->isNegative()) {
throw new DceSecurityException(
'Local identifier out of bounds; it must be a value between 0 and 4294967295'
'Local identifier out of bounds; it must be a value between 0 and 4294967295',
);
}
if ($clockSeq > self::CLOCK_SEQ_HIGH || $clockSeq < self::CLOCK_SEQ_LOW) {
throw new DceSecurityException(
'Clock sequence out of bounds; it must be a value between 0 and 63'
);
throw new DceSecurityException('Clock sequence out of bounds; it must be a value between 0 and 63');
}
switch ($localDomain) {
case Uuid::DCE_DOMAIN_ORG:
if ($localIdentifier === null) {
throw new DceSecurityException(
'A local identifier must be provided for the org domain'
);
throw new DceSecurityException('A local identifier must be provided for the org domain');
}
break;
@@ -109,13 +103,11 @@ class DceSecurityGenerator implements DceSecurityGeneratorInterface
$identifierHex = $this->numberConverter->toHex($localIdentifier->toString());
// The maximum value for the local identifier is 0xffffffff, or
// 4294967295. This is 8 hexadecimal digits, so if the length of
// hexadecimal digits is greater than 8, we know the value is greater
// than 0xffffffff.
// The maximum value for the local identifier is 0xffffffff, or 4,294,967,295. This is 8 hexadecimal digits, so
// if the length of hexadecimal digits is greater than 8, we know the value is greater than 0xffffffff.
if (strlen($identifierHex) > 8) {
throw new DceSecurityException(
'Local identifier out of bounds; it must be a value between 0 and 4294967295'
'Local identifier out of bounds; it must be a value between 0 and 4294967295',
);
}
src/Generator/DceSecurityGeneratorInterface.php
+11 -16
View File
@@ -19,28 +19,23 @@ use Ramsey\Uuid\Type\Hexadecimal;
use Ramsey\Uuid\Type\Integer as IntegerObject;
/**
* A DCE Security generator generates strings of binary data based on a local
* domain, local identifier, node ID, clock sequence, and the current time
* A DCE Security generator generates strings of binary data based on a local domain, local identifier, node ID, clock
* sequence, and the current time
*
* @see UuidV2
*/
interface DceSecurityGeneratorInterface
{
/**
* Generate a binary string from a local domain, local identifier, node ID,
* clock sequence, and current time
* Generate a binary string from a local domain, local identifier, node ID, clock sequence, and current time
*
* @param int $localDomain The local domain to use when generating bytes,
* according to DCE Security
* @param IntegerObject|null $localIdentifier The local identifier for the
* given domain; this may be a UID or GID on POSIX systems, if the local
* domain is person or group, or it may be a site-defined identifier
* 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 $localDomain The local domain to use when generating bytes, according to DCE Security
* @param IntegerObject | null $localIdentifier The local identifier for the given domain; this may be a UID or GID
* on POSIX systems if the local domain is "person" or "group," or it may be a site-defined identifier 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
*
* @return string A binary string
*/
@@ -48,6 +43,6 @@ interface DceSecurityGeneratorInterface
int $localDomain,
?IntegerObject $localIdentifier = null,
?Hexadecimal $node = null,
?int $clockSeq = null
?int $clockSeq = null,
): string;
}
src/Generator/DefaultNameGenerator.php
+1 -2
View File
@@ -21,8 +21,7 @@ use ValueError;
use function hash;
/**
* DefaultNameGenerator generates strings of binary data based on a namespace,
* name, and hashing algorithm
* DefaultNameGenerator generates strings of binary data based on a namespace, name, and hashing algorithm
*/
class DefaultNameGenerator implements NameGeneratorInterface
{
src/Generator/DefaultTimeGenerator.php
+10 -21
View File
@@ -35,15 +35,14 @@ use function strlen;
use const STR_PAD_LEFT;
/**
* DefaultTimeGenerator generates strings of binary data based on a node ID,
* clock sequence, and the current time
* DefaultTimeGenerator generates strings of binary data based on a node ID, clock sequence, and the current time
*/
class DefaultTimeGenerator implements TimeGeneratorInterface
{
public function __construct(
private NodeProviderInterface $nodeProvider,
private TimeConverterInterface $timeConverter,
private TimeProviderInterface $timeProvider
private TimeProviderInterface $timeProvider,
) {
}
@@ -63,14 +62,10 @@ class DefaultTimeGenerator implements TimeGeneratorInterface
if ($clockSeq === null) {
try {
// This does not use "stable storage"; see RFC 4122, Section 4.2.1.1.
// This does not use "stable storage"; see RFC 9562, section 6.3.
$clockSeq = random_int(0, 0x3fff);
} catch (Throwable $exception) {
throw new RandomSourceException(
$exception->getMessage(),
(int) $exception->getCode(),
$exception
);
throw new RandomSourceException($exception->getMessage(), (int) $exception->getCode(), $exception);
}
}
@@ -84,26 +79,20 @@ class DefaultTimeGenerator implements TimeGeneratorInterface
$timeHex = str_pad($uuidTime->toString(), 16, '0', STR_PAD_LEFT);
if (strlen($timeHex) !== 16) {
throw new TimeSourceException(sprintf(
'The generated time of \'%s\' is larger than expected',
$timeHex
));
throw new TimeSourceException(sprintf('The generated time of \'%s\' is larger than expected', $timeHex));
}
$timeBytes = (string) hex2bin($timeHex);
return $timeBytes[4] . $timeBytes[5] . $timeBytes[6] . $timeBytes[7]
. $timeBytes[2] . $timeBytes[3]
. $timeBytes[0] . $timeBytes[1]
. pack('n*', $clockSeq)
. $node;
. $timeBytes[2] . $timeBytes[3] . $timeBytes[0] . $timeBytes[1]
. pack('n*', $clockSeq) . $node;
}
/**
* Uses the node provider given when constructing this instance to get
* the node ID (usually a MAC address)
* Uses the node provider given when constructing this instance to get the node ID (usually a MAC address)
*
* @param int|string|null $node A node value that may be used to override the node provider
* @param int | string | null $node A node value that may be used to override the node provider
*
* @return string 6-byte binary string representation of the node
*
@@ -115,7 +104,7 @@ class DefaultTimeGenerator implements TimeGeneratorInterface
$node = $this->nodeProvider->getNode();
}
// Convert the node to hex, if it is still an integer.
// Convert the node to hex if it is still an integer.
if (is_int($node)) {
$node = dechex($node);
}
src/Generator/NameGeneratorFactory.php
+1 -2
View File
@@ -15,8 +15,7 @@ declare(strict_types=1);
namespace Ramsey\Uuid\Generator;
/**
* NameGeneratorFactory retrieves a default name generator, based on the
* environment
* NameGeneratorFactory retrieves a default name generator, based on the environment
*/
class NameGeneratorFactory
{
src/Generator/NameGeneratorInterface.php
+3 -4
View File
@@ -17,14 +17,13 @@ namespace Ramsey\Uuid\Generator;
use Ramsey\Uuid\UuidInterface;
/**
* A name generator generates strings of binary data created by hashing together
* a namespace with a name, according to a hashing algorithm
* A name generator generates strings of binary data created by hashing together a namespace with a name, according to a
* hashing algorithm
*/
interface NameGeneratorInterface
{
/**
* Generate a binary string from a namespace and name hashed together with
* the specified hashing algorithm
* Generate a binary string from a namespace and name hashed together with the specified hashing algorithm
*
* @param UuidInterface $ns The namespace
* @param string $name The name to use for creating a UUID
src/Generator/PeclUuidNameGenerator.php
+2 -6
View File
@@ -23,8 +23,7 @@ use function uuid_generate_sha1;
use function uuid_parse;
/**
* PeclUuidNameGenerator generates strings of binary data from a namespace and a
* name, using ext-uuid
* PeclUuidNameGenerator generates strings of binary data from a namespace and a name, using ext-uuid
*
* @link https://pecl.php.net/package/uuid ext-uuid
*/
@@ -36,10 +35,7 @@ class PeclUuidNameGenerator implements NameGeneratorInterface
'md5' => uuid_generate_md5($ns->toString(), $name),
'sha1' => uuid_generate_sha1($ns->toString(), $name),
default => throw new NameException(
sprintf(
'Unable to hash namespace and name with algorithm \'%s\'',
$hashAlgorithm
)
sprintf('Unable to hash namespace and name with algorithm \'%s\'', $hashAlgorithm),
),
};
src/Generator/PeclUuidTimeGenerator.php
+1 -2
View File
@@ -20,8 +20,7 @@ use function uuid_parse;
use const UUID_TYPE_TIME;
/**
* PeclUuidTimeGenerator generates strings of binary data for time-base UUIDs,
* using ext-uuid
* PeclUuidTimeGenerator generates strings of binary data for time-base UUIDs, using ext-uuid
*
* @link https://pecl.php.net/package/uuid ext-uuid
*/
src/Generator/RandomBytesGenerator.php
+2 -7
View File
@@ -18,8 +18,7 @@ use Ramsey\Uuid\Exception\RandomSourceException;
use Throwable;
/**
* RandomBytesGenerator generates strings of random binary data using the
* built-in `random_bytes()` PHP function
* RandomBytesGenerator generates strings of random binary data using the built-in `random_bytes()` PHP function
*
* @link http://php.net/random_bytes random_bytes()
*/
@@ -35,11 +34,7 @@ class RandomBytesGenerator implements RandomGeneratorInterface
try {
return random_bytes($length);
} catch (Throwable $exception) {
throw new RandomSourceException(
$exception->getMessage(),
(int) $exception->getCode(),
$exception
);
throw new RandomSourceException($exception->getMessage(), (int) $exception->getCode(), $exception);
}
}
}
src/Generator/RandomGeneratorFactory.php
+1 -2
View File
@@ -15,8 +15,7 @@ declare(strict_types=1);
namespace Ramsey\Uuid\Generator;
/**
* RandomGeneratorFactory retrieves a default random generator, based on the
* environment
* RandomGeneratorFactory retrieves a default random generator, based on the environment
*/
class RandomGeneratorFactory
{
src/Generator/RandomGeneratorInterface.php
+1 -1
View File
@@ -22,7 +22,7 @@ interface RandomGeneratorInterface
/**
* Generates a string of randomized binary data
*
* @param int<1, max> $length The number of bytes of random binary data to generate
* @param int<1, max> $length The number of bytes to generate of random binary data
*
* @return string A binary string
*/
src/Generator/RandomLibAdapter.php
+6 -8
View File
@@ -18,12 +18,10 @@ use RandomLib\Factory;
use RandomLib\Generator;
/**
* RandomLibAdapter generates strings of random binary data using the
* paragonie/random-lib library
* RandomLibAdapter generates strings of random binary data using the paragonie/random-lib library
*
* @deprecated This class will be removed in 5.0.0. Use the default
* RandomBytesGenerator or implement your own generator that implements
* RandomGeneratorInterface.
* @deprecated This class will be removed in 5.0.0. Use the default RandomBytesGenerator or implement your own generator
* that implements RandomGeneratorInterface.
*
* @link https://packagist.org/packages/paragonie/random-lib paragonie/random-lib
*/
@@ -34,10 +32,10 @@ class RandomLibAdapter implements RandomGeneratorInterface
/**
* Constructs a RandomLibAdapter
*
* By default, if no Generator is passed in, this creates a high-strength
* generator to use when generating random binary data.
* By default, if no Generator is passed in, this creates a high-strength generator to use when generating random
* binary data.
*
* @param Generator|null $generator The generator to use when generating binary data
* @param Generator | null $generator The generator to use when generating binary data
*/
public function __construct(?Generator $generator = null)
{
src/Generator/TimeGeneratorFactory.php
+3 -8
View File
@@ -19,15 +19,14 @@ use Ramsey\Uuid\Provider\NodeProviderInterface;
use Ramsey\Uuid\Provider\TimeProviderInterface;
/**
* TimeGeneratorFactory retrieves a default time generator, based on the
* environment
* TimeGeneratorFactory retrieves a default time generator, based on the environment
*/
class TimeGeneratorFactory
{
public function __construct(
private NodeProviderInterface $nodeProvider,
private TimeConverterInterface $timeConverter,
private TimeProviderInterface $timeProvider
private TimeProviderInterface $timeProvider,
) {
}
@@ -36,10 +35,6 @@ class TimeGeneratorFactory
*/
public function getGenerator(): TimeGeneratorInterface
{
return new DefaultTimeGenerator(
$this->nodeProvider,
$this->timeConverter,
$this->timeProvider
);
return new DefaultTimeGenerator($this->nodeProvider, $this->timeConverter, $this->timeProvider);
}
}
src/Generator/TimeGeneratorInterface.php
+5 -8
View File
@@ -17,20 +17,17 @@ namespace Ramsey\Uuid\Generator;
use Ramsey\Uuid\Type\Hexadecimal;
/**
* A time generator generates strings of binary data based on a node ID,
* clock sequence, and the current time
* A time generator generates strings of binary data based on a node ID, clock sequence, and the current time
*/
interface TimeGeneratorInterface
{
/**
* Generate a binary string from a node ID, clock sequence, and current time
*
* @param Hexadecimal|int|string|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 Hexadecimal | int | string | 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
*
* @return string A binary string
*/
src/Generator/UnixTimeGenerator.php
+14 -24
View File
@@ -31,11 +31,10 @@ use const PHP_INT_SIZE;
use const STR_PAD_LEFT;
/**
* UnixTimeGenerator generates bytes that combine a 48-bit timestamp in
* milliseconds since the Unix Epoch with 80 random bits
* UnixTimeGenerator generates bytes, combining a 48-bit timestamp in milliseconds since the Unix Epoch with 80 random bits
*
* Code and concepts within this class are borrowed from the symfony/uid package
* and are used under the terms of the MIT license distributed with symfony/uid.
* Code and concepts within this class are borrowed from the symfony/uid package and are used under the terms of the MIT
* license distributed with symfony/uid.
*
* symfony/uid is copyright (c) Fabien Potencier.
*
@@ -57,17 +56,14 @@ class UnixTimeGenerator implements TimeGeneratorInterface
public function __construct(
private RandomGeneratorInterface $randomGenerator,
private int $intSize = PHP_INT_SIZE
private int $intSize = PHP_INT_SIZE,
) {
}
/**
* @param Hexadecimal|int|string|null $node Unused in this generator
* @param int|null $clockSeq Unused in this generator
* @param DateTimeInterface $dateTime A date-time instance to use when
* generating bytes
*
* @inheritDoc
* @param Hexadecimal | int | string | null $node Unused in this generator
* @param int | null $clockSeq Unused in this generator
* @param DateTimeInterface | null $dateTime A date-time instance to use when generating bytes
*/
public function generate($node = null, ?int $clockSeq = null, ?DateTimeInterface $dateTime = null): string
{
@@ -107,23 +103,17 @@ class UnixTimeGenerator implements TimeGeneratorInterface
}
/**
* Special thanks to Nicolas Grekas for sharing the following information:
* Special thanks to Nicolas Grekas (<https://github.com/nicolas-grekas>) for sharing the following information:
*
* Within the same ms, we increment the rand part by a random 24-bit number.
*
* Instead of getting this number from random_bytes(), which is slow, we get
* it by sha512-hashing self::$seed. This produces 64 bytes of entropy,
* which we need to split in a list of 24-bit numbers. unpack() first splits
* them into 16 x 32-bit numbers; we take the first byte of each of these
* numbers to get 5 extra 24-bit numbers. Then, we consume those numbers
* one-by-one and run this logic every 21 iterations.
* Instead of getting this number from random_bytes(), which is slow, we get it by sha512-hashing self::$seed. This
* produces 64 bytes of entropy, which we need to split in a list of 24-bit numbers. `unpack()` first splits them
* into 16 x 32-bit numbers; we take the first byte of each number to get 5 extra 24-bit numbers. Then, we consume
* each number one-by-one and run this logic every 21 iterations.
*
* self::$rand holds the random part of the UUID, split into 5 x 16-bit
* numbers for x86 portability. We increment this random part by the next
* 24-bit number in the self::$seedParts list and decrement
* self::$seedIndex.
*
* @link https://twitter.com/nicolasgrekas/status/1583356938825261061 Tweet from Nicolas Grekas
* `self::$rand` holds the random part of the UUID, split into 5 x 16-bit numbers for x86 portability. We increment
* this random part by the next 24-bit number in the `self::$seedParts` list and decrement `self::$seedIndex`.
*/
private function increment(): string
{
src/Guid/Fields.php
+9 -24
View File
@@ -37,7 +37,7 @@ use function unpack;
use const STR_PAD_LEFT;
/**
* GUIDs consist of a set of named fields, according to RFC 4122
* GUIDs consist of a set of named fields, according to RFC 9562 (formerly RFC 4122)
*
* @see Guid
*
@@ -62,22 +62,19 @@ final class Fields implements FieldsInterface
{
if (strlen($this->bytes) !== 16) {
throw new InvalidArgumentException(
'The byte string must be 16 bytes long; '
. 'received ' . strlen($this->bytes) . ' bytes'
'The byte string must be 16 bytes long; received ' . strlen($this->bytes) . ' bytes',
);
}
if (!$this->isCorrectVariant()) {
throw new InvalidArgumentException(
'The byte string received does not conform to the RFC '
. '4122 or Microsoft Corporation variants'
'The byte string received does not conform to the RFC 9562 (formerly RFC 4122) '
. 'or Microsoft Corporation variants',
);
}
if (!$this->isCorrectVersion()) {
throw new InvalidArgumentException(
'The byte string received does not contain a valid version'
);
throw new InvalidArgumentException('The byte string received does not contain a valid version');
}
}
@@ -95,8 +92,8 @@ final class Fields implements FieldsInterface
pack(
'v*',
hexdec(bin2hex(substr($this->bytes, 2, 2))),
hexdec(bin2hex(substr($this->bytes, 0, 2)))
)
hexdec(bin2hex(substr($this->bytes, 0, 2))),
),
);
return new Hexadecimal($hex[1] ?? '');
@@ -106,13 +103,7 @@ final class Fields implements FieldsInterface
{
// Swap the bytes from little endian to network byte order.
/** @var string[] $hex */
$hex = unpack(
'H*',
pack(
'v',
hexdec(bin2hex(substr($this->bytes, 4, 2)))
)
);
$hex = unpack('H*', pack('v', hexdec(bin2hex(substr($this->bytes, 4, 2)))));
return new Hexadecimal($hex[1] ?? '');
}
@@ -121,13 +112,7 @@ final class Fields implements FieldsInterface
{
// Swap the bytes from little endian to network byte order.
/** @var string[] $hex */
$hex = unpack(
'H*',
pack(
'v',
hexdec(bin2hex(substr($this->bytes, 6, 2)))
)
);
$hex = unpack('H*', pack('v', hexdec(bin2hex(substr($this->bytes, 6, 2)))));
return new Hexadecimal($hex[1] ?? '');
}
src/Guid/Guid.php
+9 -13
View File
@@ -24,22 +24,18 @@ use Ramsey\Uuid\Uuid;
*
* From Wikipedia:
*
* > The first three fields are unsigned 32- and 16-bit integers and are subject
* > to swapping, while the last two fields consist of uninterpreted bytes, not
* > subject to swapping. This byte swapping applies even for versions 3, 4, and
* > 5, where the canonical fields do not correspond to the content of the UUID.
* > The first three fields are unsigned 32- and 16-bit integers and are subject to swapping, while the last two fields
* > consist of uninterpreted bytes, not subject to swapping. This byte swapping applies even for versions 3, 4, and 5,
* > where the canonical fields do not correspond to the content of the UUID.
*
* The first three fields of a GUID are encoded in little-endian byte order,
* while the last three fields are in network (big-endian) byte order. This is
* according to the history of the Microsoft definition of a GUID.
* The first three fields of a GUID are encoded in little-endian byte order, while the last three fields are in network
* (big-endian) byte order. This is according to the history of the Microsoft GUID definition.
*
* According to the .NET Guid.ToByteArray method documentation:
*
* > Note that the order of bytes in the returned byte array is different from
* > the string representation of a Guid value. The order of the beginning
* > four-byte group and the next two two-byte groups is reversed, whereas the
* > order of the last two-byte group and the closing six-byte group is the
* > same.
* > Note that the order of bytes in the returned byte array is different from the string representation of a Guid value.
* > The order of the beginning four-byte group and the next two two-byte groups is reversed, whereas the order of the
* > last two-byte group and the closing six-byte group is the same.
*
* @link https://en.wikipedia.org/wiki/Universally_unique_identifier#Variants UUID Variants on Wikipedia
* @link https://docs.microsoft.com/en-us/windows/win32/api/guiddef/ns-guiddef-guid Windows GUID structure
@@ -54,7 +50,7 @@ final class Guid extends Uuid
Fields $fields,
NumberConverterInterface $numberConverter,
CodecInterface $codec,
TimeConverterInterface $timeConverter
TimeConverterInterface $timeConverter,
) {
parent::__construct($fields, $numberConverter, $codec, $timeConverter);
}
src/Guid/GuidBuilder.php
+6 -12
View File
@@ -32,14 +32,13 @@ use Throwable;
class GuidBuilder implements UuidBuilderInterface
{
/**
* @param NumberConverterInterface $numberConverter The number converter to
* use when constructing the Guid
* @param TimeConverterInterface $timeConverter The time converter to use
* for converting timestamps extracted from a UUID to Unix timestamps
* @param NumberConverterInterface $numberConverter The number converter to use when constructing the Guid
* @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a
* UUID to Unix timestamps
*/
public function __construct(
private NumberConverterInterface $numberConverter,
private TimeConverterInterface $timeConverter
private TimeConverterInterface $timeConverter,
) {
}
@@ -54,19 +53,14 @@ class GuidBuilder implements UuidBuilderInterface
public function build(CodecInterface $codec, string $bytes): UuidInterface
{
try {
return new Guid(
$this->buildFields($bytes),
$this->numberConverter,
$codec,
$this->timeConverter
);
return new Guid($this->buildFields($bytes), $this->numberConverter, $codec, $this->timeConverter);
} catch (Throwable $e) {
throw new UnableToBuildUuidException($e->getMessage(), (int) $e->getCode(), $e);
}
}
/**
* Proxy method to allow injecting a mock, for testing
* Proxy method to allow injecting a mock for testing
*/
protected function buildFields(string $bytes): Fields
{
src/Lazy/LazyUuidFromString.php
+61 -100
View File
@@ -35,17 +35,18 @@ use function substr;
/**
* Lazy version of a UUID: its format has not been determined yet, so it is mostly only usable for string/bytes
* conversion. This object optimizes instantiation, serialization and string conversion time, at the cost of
* increased overhead for more advanced UUID operations.
* conversion. This object optimizes instantiation, serialization and string conversion time, at the cost of increased
* overhead for more advanced UUID operations.
*
* @internal this type is used internally for performance reasons and is not supposed to be directly referenced
* in consumer libraries.
* > [!NOTE]
* > The {@see FieldsInterface} does not declare methods that deprecated API relies upon: the API has been ported from
* > the {@see \Ramsey\Uuid\Uuid} definition, and is deprecated anyway.
*
* Note: the {@see FieldsInterface} does not declare methods that deprecated API
* relies upon: the API has been ported from the {@see \Ramsey\Uuid\Uuid} definition,
* and is deprecated anyway.
* Note: the deprecated API from {@see \Ramsey\Uuid\Uuid} is in use here (on purpose): it will be removed
* once the deprecated API is gone from this class too.
* > [!NOTE]
* > The deprecated API from {@see \Ramsey\Uuid\Uuid} is in use here (on purpose): it will be removed once the
* > deprecated API is gone from this class too.
*
* @internal this type is used internally for performance reasons and is not supposed to be directly referenced in consumer libraries.
*/
final class LazyUuidFromString implements UuidInterface
{
@@ -116,8 +117,7 @@ final class LazyUuidFromString implements UuidInterface
public function getNumberConverter(): NumberConverterInterface
{
return ($this->unwrapped ?? $this->unwrap())
->getNumberConverter();
return ($this->unwrapped ?? $this->unwrap())->getNumberConverter();
}
/**
@@ -125,103 +125,87 @@ final class LazyUuidFromString implements UuidInterface
*/
public function getFieldsHex(): array
{
return ($this->unwrapped ?? $this->unwrap())
->getFieldsHex();
return ($this->unwrapped ?? $this->unwrap())->getFieldsHex();
}
public function getClockSeqHiAndReservedHex(): string
{
return ($this->unwrapped ?? $this->unwrap())
->getClockSeqHiAndReservedHex();
return ($this->unwrapped ?? $this->unwrap())->getClockSeqHiAndReservedHex();
}
public function getClockSeqLowHex(): string
{
return ($this->unwrapped ?? $this->unwrap())
->getClockSeqLowHex();
return ($this->unwrapped ?? $this->unwrap())->getClockSeqLowHex();
}
public function getClockSequenceHex(): string
{
return ($this->unwrapped ?? $this->unwrap())
->getClockSequenceHex();
return ($this->unwrapped ?? $this->unwrap())->getClockSequenceHex();
}
public function getDateTime(): DateTimeInterface
{
return ($this->unwrapped ?? $this->unwrap())
->getDateTime();
return ($this->unwrapped ?? $this->unwrap())->getDateTime();
}
public function getLeastSignificantBitsHex(): string
{
return ($this->unwrapped ?? $this->unwrap())
->getLeastSignificantBitsHex();
return ($this->unwrapped ?? $this->unwrap())->getLeastSignificantBitsHex();
}
public function getMostSignificantBitsHex(): string
{
return ($this->unwrapped ?? $this->unwrap())
->getMostSignificantBitsHex();
return ($this->unwrapped ?? $this->unwrap())->getMostSignificantBitsHex();
}
public function getNodeHex(): string
{
return ($this->unwrapped ?? $this->unwrap())
->getNodeHex();
return ($this->unwrapped ?? $this->unwrap())->getNodeHex();
}
public function getTimeHiAndVersionHex(): string
{
return ($this->unwrapped ?? $this->unwrap())
->getTimeHiAndVersionHex();
return ($this->unwrapped ?? $this->unwrap())->getTimeHiAndVersionHex();
}
public function getTimeLowHex(): string
{
return ($this->unwrapped ?? $this->unwrap())
->getTimeLowHex();
return ($this->unwrapped ?? $this->unwrap())->getTimeLowHex();
}
public function getTimeMidHex(): string
{
return ($this->unwrapped ?? $this->unwrap())
->getTimeMidHex();
return ($this->unwrapped ?? $this->unwrap())->getTimeMidHex();
}
public function getTimestampHex(): string
{
return ($this->unwrapped ?? $this->unwrap())
->getTimestampHex();
return ($this->unwrapped ?? $this->unwrap())->getTimestampHex();
}
public function getUrn(): string
{
return ($this->unwrapped ?? $this->unwrap())
->getUrn();
return ($this->unwrapped ?? $this->unwrap())->getUrn();
}
public function getVariant(): ?int
{
return ($this->unwrapped ?? $this->unwrap())
->getVariant();
return ($this->unwrapped ?? $this->unwrap())->getVariant();
}
public function getVersion(): ?int
{
return ($this->unwrapped ?? $this->unwrap())
->getVersion();
return ($this->unwrapped ?? $this->unwrap())->getVersion();
}
public function compareTo(UuidInterface $other): int
{
return ($this->unwrapped ?? $this->unwrap())
->compareTo($other);
return ($this->unwrapped ?? $this->unwrap())->compareTo($other);
}
public function equals(?object $other): bool
{
if (! $other instanceof UuidInterface) {
if (!$other instanceof UuidInterface) {
return false;
}
@@ -236,20 +220,17 @@ final class LazyUuidFromString implements UuidInterface
public function getFields(): FieldsInterface
{
return ($this->unwrapped ?? $this->unwrap())
->getFields();
return ($this->unwrapped ?? $this->unwrap())->getFields();
}
public function getHex(): Hexadecimal
{
return ($this->unwrapped ?? $this->unwrap())
->getHex();
return ($this->unwrapped ?? $this->unwrap())->getHex();
}
public function getInteger(): IntegerObject
{
return ($this->unwrapped ?? $this->unwrap())
->getInteger();
return ($this->unwrapped ?? $this->unwrap())->getInteger();
}
public function toString(): string
@@ -268,11 +249,9 @@ final class LazyUuidFromString implements UuidInterface
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
* instance, you may call {@see Rfc4122FieldsInterface::getClockSeqHiAndReserved()}
* and use the arbitrary-precision math library of your choice to
* convert it to a string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getClockSeqHiAndReserved()}
* and use the arbitrary-precision math library of your choice to convert it to a string integer.
*/
public function getClockSeqHiAndReserved(): string
{
@@ -285,11 +264,9 @@ final class LazyUuidFromString implements UuidInterface
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
* instance, you may call {@see Rfc4122FieldsInterface::getClockSeqLow()}
* and use the arbitrary-precision math library of your choice to
* convert it to a string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getClockSeqLow()} and use
* the arbitrary-precision math library of your choice to convert it to a string integer.
*/
public function getClockSeqLow(): string
{
@@ -302,11 +279,9 @@ final class LazyUuidFromString implements UuidInterface
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
* instance, you may call {@see Rfc4122FieldsInterface::getClockSeq()}
* and use the arbitrary-precision math library of your choice to
* convert it to a string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getClockSeq()} and use the
* arbitrary-precision math library of your choice to convert it to a string integer.
*/
public function getClockSequence(): string
{
@@ -319,37 +294,31 @@ final class LazyUuidFromString implements UuidInterface
}
/**
* @deprecated This method will be removed in 5.0.0. There is no direct
* alternative, but the same information may be obtained by splitting
* in half the value returned by {@see UuidInterface::getHex()}.
* @deprecated This method will be removed in 5.0.0. There is no direct alternative, but the same information may be
* obtained by splitting in half the value returned by {@see UuidInterface::getHex()}.
*/
public function getLeastSignificantBits(): string
{
$instance = ($this->unwrapped ?? $this->unwrap());
return $instance->getNumberConverter()
->fromHex(substr($instance->getHex()->toString(), 16));
return $instance->getNumberConverter()->fromHex(substr($instance->getHex()->toString(), 16));
}
/**
* @deprecated This method will be removed in 5.0.0. There is no direct
* alternative, but the same information may be obtained by splitting
* in half the value returned by {@see UuidInterface::getHex()}.
* @deprecated This method will be removed in 5.0.0. There is no direct alternative, but the same information may be
* obtained by splitting in half the value returned by {@see UuidInterface::getHex()}.
*/
public function getMostSignificantBits(): string
{
$instance = ($this->unwrapped ?? $this->unwrap());
return $instance->getNumberConverter()
->fromHex(substr($instance->getHex()->toString(), 0, 16));
return $instance->getNumberConverter()->fromHex(substr($instance->getHex()->toString(), 0, 16));
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
* instance, you may call {@see Rfc4122FieldsInterface::getNode()}
* and use the arbitrary-precision math library of your choice to
* convert it to a string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getNode()} and use the
* arbitrary-precision math library of your choice to convert it to a string integer.
*/
public function getNode(): string
{
@@ -362,11 +331,9 @@ final class LazyUuidFromString implements UuidInterface
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
* instance, you may call {@see Rfc4122FieldsInterface::getTimeHiAndVersion()}
* and use the arbitrary-precision math library of your choice to
* convert it to a string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getTimeHiAndVersion()} and
* use the arbitrary-precision math library of your choice to convert it to a string integer.
*/
public function getTimeHiAndVersion(): string
{
@@ -379,11 +346,9 @@ final class LazyUuidFromString implements UuidInterface
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
* instance, you may call {@see Rfc4122FieldsInterface::getTimeLow()}
* and use the arbitrary-precision math library of your choice to
* convert it to a string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getTimeLow()} and use the
* arbitrary-precision math library of your choice to convert it to a string integer.
*/
public function getTimeLow(): string
{
@@ -396,11 +361,9 @@ final class LazyUuidFromString implements UuidInterface
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
* instance, you may call {@see Rfc4122FieldsInterface::getTimeMid()}
* and use the arbitrary-precision math library of your choice to
* convert it to a string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getTimeMid()} and use the
* arbitrary-precision math library of your choice to convert it to a string integer.
*/
public function getTimeMid(): string
{
@@ -413,11 +376,9 @@ final class LazyUuidFromString implements UuidInterface
}
/**
* @deprecated Use {@see UuidInterface::getFields()} to get a
* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
* instance, you may call {@see Rfc4122FieldsInterface::getTimestamp()}
* and use the arbitrary-precision math library of your choice to
* convert it to a string integer.
* @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
* {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getTimestamp()} and use
* the arbitrary-precision math library of your choice to convert it to a string integer.
*/
public function getTimestamp(): string
{
src/Math/BrickMathCalculator.php
+1 -1
View File
@@ -81,7 +81,7 @@ final class BrickMathCalculator implements CalculatorInterface
int $roundingMode,
int $scale,
NumberInterface $dividend,
NumberInterface ...$divisors
NumberInterface ...$divisors,
): NumberInterface {
$brickRounding = $this->getBrickRoundingMode($roundingMode);
src/Math/CalculatorInterface.php
+3 -4
View File
@@ -61,9 +61,8 @@ interface CalculatorInterface
* @param int $roundingMode The RoundingMode constant to use for this operation
* @param int $scale The scale to use for this operation
* @param NumberInterface $dividend The integer to be divided
* @param NumberInterface ...$divisors The integers to divide $dividend by, in
* the order in which the division operations should take place
* (left-to-right)
* @param NumberInterface ...$divisors The integers to divide $dividend by, in the order in which the division
* operations should take place (left-to-right)
*
* @return NumberInterface The quotient of dividing the provided parameters left-to-right
*/
@@ -71,7 +70,7 @@ interface CalculatorInterface
int $roundingMode,
int $scale,
NumberInterface $dividend,
NumberInterface ...$divisors
NumberInterface ...$divisors,
): NumberInterface;
/**
src/Math/RoundingMode.php
+81 -100
View File
@@ -31,19 +31,91 @@ declare(strict_types=1);
namespace Ramsey\Uuid\Math;
/**
* Specifies a rounding behavior for numerical operations capable of discarding
* precision.
* Specifies a rounding behavior for numerical operations capable of discarding precision.
*
* Each rounding mode indicates how the least significant returned digit of a
* rounded result is to be calculated. If fewer digits are returned than the
* digits needed to represent the exact numerical result, the discarded digits
* will be referred to as the discarded fraction regardless the digits'
* contribution to the value of the number. In other words, considered as a
* numerical value, the discarded fraction could have an absolute value greater
* than one.
* Each rounding mode indicates how the least significant returned digit of a rounded result is to be calculated. If
* fewer digits are returned than the digits needed to represent the exact numerical result, the discarded digits will
* be referred to as the discarded fraction regardless of the digits' contribution to the value of the number. In other
* words, considered as a numerical value, the discarded fraction could have an absolute value greater than one.
*/
final class RoundingMode
{
/**
* Asserts that the requested operation has an exact result; hence no rounding is necessary.
*/
public const UNNECESSARY = 0;
/**
* Rounds away from zero.
*
* Always increments the digit prior to a nonzero discarded fraction. Note that this rounding mode never decreases
* the magnitude of the calculated value.
*/
public const UP = 1;
/**
* Rounds towards zero.
*
* Never increments the digit prior to a discarded fraction (i.e., truncates). Note that this rounding mode never
* increases the magnitude of the calculated value.
*/
public const DOWN = 2;
/**
* Rounds towards positive infinity.
*
* If the result is positive, behaves as for UP; if negative, behaves as for DOWN. Note that this rounding mode
* never decreases the calculated value.
*/
public const CEILING = 3;
/**
* Rounds towards negative infinity.
*
* If the result is positive, behave as for DOWN; if negative, behave as for UP. Note that this rounding mode never
* increases the calculated value.
*/
public const FLOOR = 4;
/**
* Rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case round up.
*
* Behaves as for UP if the discarded fraction is >= 0.5; otherwise, behaves as for DOWN. Note that this is the
* rounding mode commonly taught at school.
*/
public const HALF_UP = 5;
/**
* Rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case round down.
*
* Behaves as for UP if the discarded fraction is > 0.5; otherwise, behaves as for DOWN.
*/
public const HALF_DOWN = 6;
/**
* Rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case round towards positive infinity.
*
* If the result is positive, behaves as for HALF_UP; if negative, behaves as for HALF_DOWN.
*/
public const HALF_CEILING = 7;
/**
* Rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case round towards negative infinity.
*
* If the result is positive, behaves as for HALF_DOWN; if negative, behaves as for HALF_UP.
*/
public const HALF_FLOOR = 8;
/**
* Rounds towards the "nearest neighbor" unless both neighbors are equidistant, in which case rounds towards the even neighbor.
*
* Behaves as for HALF_UP if the digit to the left of the discarded fraction is odd; behaves as for HALF_DOWN if it's even.
*
* Note that this is the rounding mode that statistically minimizes cumulative error when applied repeatedly over a
* sequence of calculations. It is sometimes known as "Banker's rounding", and is chiefly used in the USA.
*/
public const HALF_EVEN = 9;
/**
* Private constructor. This class is not instantiable.
*
@@ -52,95 +124,4 @@ final class RoundingMode
private function __construct()
{
}
/**
* Asserts that the requested operation has an exact result, hence no
* rounding is necessary.
*/
public const UNNECESSARY = 0;
/**
* Rounds away from zero.
*
* Always increments the digit prior to a nonzero discarded fraction.
* Note that this rounding mode never decreases the magnitude of the
* calculated value.
*/
public const UP = 1;
/**
* Rounds towards zero.
*
* Never increments the digit prior to a discarded fraction (i.e.,
* truncates). Note that this rounding mode never increases the magnitude of
* the calculated value.
*/
public const DOWN = 2;
/**
* Rounds towards positive infinity.
*
* If the result is positive, behaves as for UP; if negative, behaves as for
* DOWN. Note that this rounding mode never decreases the calculated value.
*/
public const CEILING = 3;
/**
* Rounds towards negative infinity.
*
* If the result is positive, behave as for DOWN; if negative, behave as for
* UP. Note that this rounding mode never increases the calculated value.
*/
public const FLOOR = 4;
/**
* Rounds towards "nearest neighbor" unless both neighbors are equidistant,
* in which case round up.
*
* Behaves as for UP if the discarded fraction is >= 0.5; otherwise, behaves
* as for DOWN. Note that this is the rounding mode commonly taught at
* school.
*/
public const HALF_UP = 5;
/**
* Rounds towards "nearest neighbor" unless both neighbors are equidistant,
* in which case round down.
*
* Behaves as for UP if the discarded fraction is > 0.5; otherwise, behaves
* as for DOWN.
*/
public const HALF_DOWN = 6;
/**
* Rounds towards "nearest neighbor" unless both neighbors are equidistant,
* in which case round towards positive infinity.
*
* If the result is positive, behaves as for HALF_UP; if negative, behaves
* as for HALF_DOWN.
*/
public const HALF_CEILING = 7;
/**
* Rounds towards "nearest neighbor" unless both neighbors are equidistant,
* in which case round towards negative infinity.
*
* If the result is positive, behaves as for HALF_DOWN; if negative, behaves
* as for HALF_UP.
*/
public const HALF_FLOOR = 8;
/**
* Rounds towards the "nearest neighbor" unless both neighbors are
* equidistant, in which case rounds towards the even neighbor.
*
* Behaves as for HALF_UP if the digit to the left of the discarded fraction
* is odd; behaves as for HALF_DOWN if it's even.
*
* Note that this is the rounding mode that statistically minimizes
* cumulative error when applied repeatedly over a sequence of calculations.
* It is sometimes known as "Banker's rounding", and is chiefly used in the
* USA.
*/
public const HALF_EVEN = 9;
}
src/Nonstandard/Fields.php
+5 -8
View File
@@ -31,14 +31,12 @@ use function substr;
use const STR_PAD_LEFT;
/**
* Nonstandard UUID fields do not conform to the RFC 4122 standard
* Nonstandard UUID fields do not conform to the RFC 9562 (formerly RFC 4122) standard
*
* Since some systems may create nonstandard UUIDs, this implements the
* Rfc4122\FieldsInterface, so that functionality of a nonstandard UUID is not
* degraded, in the event these UUIDs are expected to contain RFC 4122 fields.
* Since some systems may create nonstandard UUIDs, this implements the {@see FieldsInterface}, so that functionality of
* a nonstandard UUID is not degraded, in the event these UUIDs are expected to contain RFC 9562 (formerly RFC 4122) fields.
*
* Internally, this class represents the fields together as a 16-byte binary
* string.
* Internally, this class represents the fields together as a 16-byte binary string.
*
* @immutable
*/
@@ -56,8 +54,7 @@ final class Fields implements FieldsInterface
{
if (strlen($this->bytes) !== 16) {
throw new InvalidArgumentException(
'The byte string must be 16 bytes long; '
. 'received ' . strlen($this->bytes) . ' bytes'
'The byte string must be 16 bytes long; received ' . strlen($this->bytes) . ' bytes',
);
}
}
src/Nonstandard/Uuid.php
+2 -2
View File
@@ -20,7 +20,7 @@ use Ramsey\Uuid\Converter\TimeConverterInterface;
use Ramsey\Uuid\Uuid as BaseUuid;
/**
* Nonstandard\Uuid is a UUID that doesn't conform to RFC 4122
* Nonstandard\Uuid is a UUID that doesn't conform to RFC 9562 (formerly RFC 4122)
*
* @immutable
*/
@@ -30,7 +30,7 @@ final class Uuid extends BaseUuid
Fields $fields,
NumberConverterInterface $numberConverter,
CodecInterface $codec,
TimeConverterInterface $timeConverter
TimeConverterInterface $timeConverter,
) {
parent::__construct($fields, $numberConverter, $codec, $timeConverter);
}
src/Nonstandard/UuidBuilder.php
+7 -14
View File
@@ -30,14 +30,13 @@ use Throwable;
class UuidBuilder implements UuidBuilderInterface
{
/**
* @param NumberConverterInterface $numberConverter The number converter to
* use when constructing the Nonstandard\Uuid
* @param TimeConverterInterface $timeConverter The time converter to use
* for converting timestamps extracted from a UUID to Unix timestamps
* @param NumberConverterInterface $numberConverter The number converter to use when constructing the Nonstandard\Uuid
* @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a
* UUID to Unix timestamps
*/
public function __construct(
private NumberConverterInterface $numberConverter,
private TimeConverterInterface $timeConverter
private TimeConverterInterface $timeConverter,
) {
}
@@ -47,25 +46,19 @@ class UuidBuilder implements UuidBuilderInterface
* @param CodecInterface $codec The codec to use for building this instance
* @param string $bytes The byte string from which to construct a UUID
*
* @return Uuid The Nonstandard\UuidBuilder returns an instance of
* Nonstandard\Uuid
* @return Uuid The Nonstandard\UuidBuilder returns an instance of Nonstandard\Uuid
*/
public function build(CodecInterface $codec, string $bytes): UuidInterface
{
try {
return new Uuid(
$this->buildFields($bytes),
$this->numberConverter,
$codec,
$this->timeConverter
);
return new Uuid($this->buildFields($bytes), $this->numberConverter, $codec, $this->timeConverter);
} catch (Throwable $e) {
throw new UnableToBuildUuidException($e->getMessage(), (int) $e->getCode(), $e);
}
}
/**
* Proxy method to allow injecting a mock, for testing
* Proxy method to allow injecting a mock for testing
*/
protected function buildFields(string $bytes): Fields
{
src/Nonstandard/UuidV6.php
+13 -15
View File
@@ -26,13 +26,14 @@ use Ramsey\Uuid\Rfc4122\UuidV1;
use Ramsey\Uuid\Uuid as BaseUuid;
/**
* Reordered time, or version 6, UUIDs include timestamp, clock sequence, and
* node values that are combined into a 128-bit unsigned integer
* Reordered time, or version 6, UUIDs include timestamp, clock sequence, and node values that are combined into a
* 128-bit unsigned integer
*
* @deprecated Use {@see \Ramsey\Uuid\Rfc4122\UuidV6} instead.
*
* @link https://github.com/uuid6/uuid6-ietf-draft UUID version 6 IETF draft
* @link http://gh.peabody.io/uuidv6/ "Version 6" UUIDs
* @link https://www.rfc-editor.org/rfc/rfc9562#section-5.6 RFC 9562, 5.6. UUID Version 6
*
* @immutable
*/
@@ -41,26 +42,23 @@ class UuidV6 extends BaseUuid implements UuidInterface
use TimeTrait;
/**
* Creates a version 6 (reordered time) UUID
* Creates a version 6 (reordered Gregorian time) UUID
*
* @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID
* @param NumberConverterInterface $numberConverter The number converter to use
* for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding
* UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use
* for converting timestamps extracted from a UUID to unix timestamps
* @param NumberConverterInterface $numberConverter The number converter to use for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a
* UUID to unix timestamps
*/
public function __construct(
Rfc4122FieldsInterface $fields,
NumberConverterInterface $numberConverter,
CodecInterface $codec,
TimeConverterInterface $timeConverter
TimeConverterInterface $timeConverter,
) {
if ($fields->getVersion() !== Uuid::UUID_TYPE_REORDERED_TIME) {
if ($fields->getVersion() !== BaseUuid::UUID_TYPE_REORDERED_TIME) {
throw new InvalidArgumentException(
'Fields used to create a UuidV6 must represent a '
. 'version 6 (reordered time) UUID'
'Fields used to create a UuidV6 must represent a version 6 (reordered time) UUID',
);
}
@@ -80,7 +78,7 @@ class UuidV6 extends BaseUuid implements UuidInterface
. substr($hex, 16);
/** @var LazyUuidFromString $uuid */
$uuid = Uuid::fromBytes((string) hex2bin($hex));
$uuid = BaseUuid::fromBytes((string) hex2bin($hex));
return $uuid->toUuidV1();
}
@@ -98,7 +96,7 @@ class UuidV6 extends BaseUuid implements UuidInterface
. substr($hex, 16);
/** @var LazyUuidFromString $uuid */
$uuid = Uuid::fromBytes((string) hex2bin($hex));
$uuid = BaseUuid::fromBytes((string) hex2bin($hex));
return $uuid->toUuidV6();
}
src/Provider/Dce/SystemDceSecurityProvider.php
+17 -25
View File
@@ -41,7 +41,7 @@ class SystemDceSecurityProvider implements DceSecurityProviderInterface
*/
public function getUid(): IntegerObject
{
/** @var int|float|string|IntegerObject|null $uid */
/** @var IntegerObject | int | float | string | null $uid */
static $uid = null;
if ($uid instanceof IntegerObject) {
@@ -54,9 +54,8 @@ class SystemDceSecurityProvider implements DceSecurityProviderInterface
if ($uid === '') {
throw new DceSecurityException(
'Unable to get a user identifier using the system DCE '
. 'Security provider; please provide a custom identifier or '
. 'use a different provider'
'Unable to get a user identifier using the system DCE Security provider; please provide a custom '
. 'identifier or use a different provider',
);
}
@@ -72,7 +71,7 @@ class SystemDceSecurityProvider implements DceSecurityProviderInterface
*/
public function getGid(): IntegerObject
{
/** @var int|float|string|IntegerObject|null $gid */
/** @var IntegerObject | int | float | string | null $gid */
static $gid = null;
if ($gid instanceof IntegerObject) {
@@ -85,9 +84,8 @@ class SystemDceSecurityProvider implements DceSecurityProviderInterface
if ($gid === '') {
throw new DceSecurityException(
'Unable to get a group identifier using the system DCE '
. 'Security provider; please provide a custom identifier or '
. 'use a different provider'
'Unable to get a group identifier using the system DCE Security provider; please provide a custom '
. 'identifier or use a different provider',
);
}
@@ -131,9 +129,7 @@ class SystemDceSecurityProvider implements DceSecurityProviderInterface
*/
private function hasShellExec(): bool
{
$disabledFunctions = strtolower((string) ini_get('disable_functions'));
return !str_contains($disabledFunctions, 'shell_exec');
return !str_contains(strtolower((string) ini_get('disable_functions')), 'shell_exec');
}
/**
@@ -150,17 +146,14 @@ class SystemDceSecurityProvider implements DceSecurityProviderInterface
/**
* Returns the user identifier for a user on a Windows system
*
* Windows does not have the same concept as an effective POSIX UID for the
* running script. Instead, each user is uniquely identified by an SID
* (security identifier). The SID includes three 32-bit unsigned integers
* that make up a unique domain identifier, followed by an RID (relative
* identifier) that we will use as the UID. The primary caveat is that this
* UID may not be unique to the system, since it is, instead, unique to the
* domain.
* Windows does not have the same concept as an effective POSIX UID for the running script. Instead, each user is
* uniquely identified by an SID (security identifier). The SID includes three 32-bit unsigned integers that make up
* a unique domain identifier, followed by an RID (relative identifier) that we will use as the UID. The primary
* caveat is that this UID may not be unique to the system, since it is, instead, unique to the domain.
*
* @link https://www.lifewire.com/what-is-an-sid-number-2626005 What Is an SID Number?
* @link https://bit.ly/30vE7NM Well-known SID Structures
* @link https://bit.ly/2FWcYKJ Well-known security identifiers in Windows operating systems
* @link https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-dtyp/81d92bba-d22b-4a8c-908a-554ab29148ab Well-known SID Structures
* @link https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/manage/understand-security-identifiers#well-known-sids Well-known SIDs
* @link https://www.windows-commandline.com/get-sid-of-user/ Get SID of user
*/
private function getWindowsUid(): string
@@ -183,11 +176,10 @@ class SystemDceSecurityProvider implements DceSecurityProviderInterface
/**
* Returns a group identifier for a user on a Windows system
*
* Since Windows does not have the same concept as an effective POSIX GID
* for the running script, we will get the local group memberships for the
* user running the script. Then, we will get the SID (security identifier)
* for the first group that appears in that list. Finally, we will return
* the RID (relative identifier) for the group and use that as the GID.
* Since Windows does not have the same concept as an effective POSIX GID for the running script, we will get the
* local group memberships for the user running the script. Then, we will get the SID (security identifier) for the
* first group that appears in that list. Finally, we will return the RID (relative identifier) for the group and
* use that as the GID.
*
* @link https://www.windows-commandline.com/list-of-user-groups-command-line/ List of user groups command line
*/
src/Provider/DceSecurityProviderInterface.php
+1 -2
View File
@@ -18,8 +18,7 @@ use Ramsey\Uuid\Rfc4122\UuidV2;
use Ramsey\Uuid\Type\Integer as IntegerObject;
/**
* A DCE provider provides access to local domain identifiers for version 2,
* DCE Security, UUIDs
* A DCE provider provides access to local domain identifiers for version 2, DCE Security, UUIDs
*
* @see UuidV2
*/
src/Provider/Node/FallbackNodeProvider.php
+2 -7
View File
@@ -19,8 +19,7 @@ use Ramsey\Uuid\Provider\NodeProviderInterface;
use Ramsey\Uuid\Type\Hexadecimal;
/**
* FallbackNodeProvider retrieves the system node ID by stepping through a list
* of providers until a node ID can be obtained
* FallbackNodeProvider retrieves the system node ID by stepping through a list of providers until a node ID can be obtained
*/
class FallbackNodeProvider implements NodeProviderInterface
{
@@ -45,10 +44,6 @@ class FallbackNodeProvider implements NodeProviderInterface
}
}
throw new NodeException(
'Unable to find a suitable node provider',
0,
$lastProviderException
);
throw new NodeException(message: 'Unable to find a suitable node provider', previous: $lastProviderException);
}
}
src/Provider/Node/NodeProviderCollection.php
+7 -13
View File
@@ -21,10 +21,10 @@ use Ramsey\Uuid\Type\Hexadecimal;
/**
* A collection of NodeProviderInterface objects
*
* @deprecated this class has been deprecated, and will be removed in 5.0.0. The use-case for this class comes from
* a pre-`phpstan/phpstan` and pre-`vimeo/psalm` ecosystem, in which type safety had to be mostly enforced
* at runtime: that is no longer necessary, now that you can safely verify your code to be correct, and use
* more generic types like `iterable<T>` instead.
* @deprecated this class has been deprecated and will be removed in 5.0.0. The use-case for this class comes from a
* pre-`phpstan/phpstan` and pre-`vimeo/psalm` ecosystem, in which type safety had to be mostly enforced at runtime:
* that is no longer necessary, now that you can safely verify your code to be correct and use more generic types
* like `iterable<T>` instead.
*
* @extends AbstractCollection<NodeProviderInterface>
*/
@@ -38,8 +38,7 @@ class NodeProviderCollection extends AbstractCollection
/**
* Re-constructs the object from its serialized form
*
* @param string $serialized The serialized PHP string to unserialize into
* a UuidInterface instance
* @param string $serialized The serialized PHP string to unserialize into a UuidInterface instance
*/
public function unserialize($serialized): void
{
@@ -53,12 +52,7 @@ class NodeProviderCollection extends AbstractCollection
],
]);
$this->data = array_filter(
$data,
function ($unserialized): bool {
/** @phpstan-ignore-next-line */
return $unserialized instanceof NodeProviderInterface;
}
);
/** @phpstan-ignore-next-line */
$this->data = array_filter($data, fn ($unserialized): bool => $unserialized instanceof NodeProviderInterface);
}
}
src/Provider/Node/RandomNodeProvider.php
+5 -19
View File
@@ -31,7 +31,7 @@ use const STR_PAD_LEFT;
/**
* RandomNodeProvider generates a random node ID
*
* @link http://tools.ietf.org/html/rfc4122#section-4.5 RFC 4122, § 4.5: Node IDs that Do Not Identify the Host
* @link https://www.rfc-editor.org/rfc/rfc9562#section-6.10 RFC 9562, 6.10. UUIDs That Do Not Identify the Host
*/
class RandomNodeProvider implements NodeProviderInterface
{
@@ -40,30 +40,16 @@ class RandomNodeProvider implements NodeProviderInterface
try {
$nodeBytes = random_bytes(6);
} catch (Throwable $exception) {
throw new RandomSourceException(
$exception->getMessage(),
(int) $exception->getCode(),
$exception
);
throw new RandomSourceException($exception->getMessage(), (int) $exception->getCode(), $exception);
}
// Split the node bytes for math on 32-bit systems.
$nodeMsb = substr($nodeBytes, 0, 3);
$nodeLsb = substr($nodeBytes, 3);
// Set the multicast bit; see RFC 4122, section 4.5.
$nodeMsb = hex2bin(
str_pad(
dechex(hexdec(bin2hex($nodeMsb)) | 0x010000),
6,
'0',
STR_PAD_LEFT
)
);
// Set the multicast bit; see RFC 9562, section 6.10.
$nodeMsb = hex2bin(str_pad(dechex(hexdec(bin2hex($nodeMsb)) | 0x010000), 6, '0', STR_PAD_LEFT));
// Recombine the node bytes.
$node = $nodeMsb . $nodeLsb;
return new Hexadecimal(str_pad(bin2hex($node), 12, '0', STR_PAD_LEFT));
return new Hexadecimal(str_pad(bin2hex($nodeMsb . $nodeLsb), 12, '0', STR_PAD_LEFT));
}
}
src/Provider/Node/StaticNodeProvider.php
+3 -11
View File
@@ -28,7 +28,7 @@ use const STR_PAD_LEFT;
/**
* StaticNodeProvider provides a static node value with the multicast bit set
*
* @link http://tools.ietf.org/html/rfc4122#section-4.5 RFC 4122, § 4.5: Node IDs that Do Not Identify the Host
* @link https://www.rfc-editor.org/rfc/rfc9562#section-6.10 RFC 9562, 6.10. UUIDs That Do Not Identify the Host
*/
class StaticNodeProvider implements NodeProviderInterface
{
@@ -40,9 +40,7 @@ class StaticNodeProvider implements NodeProviderInterface
public function __construct(Hexadecimal $node)
{
if (strlen($node->toString()) > 12) {
throw new InvalidArgumentException(
'Static node value cannot be greater than 12 hexadecimal characters'
);
throw new InvalidArgumentException('Static node value cannot be greater than 12 hexadecimal characters');
}
$this->node = $this->setMulticastBit($node);
@@ -60,13 +58,7 @@ class StaticNodeProvider implements NodeProviderInterface
{
$nodeHex = str_pad($node->toString(), 12, '0', STR_PAD_LEFT);
$firstOctet = substr($nodeHex, 0, 2);
$firstOctet = str_pad(
dechex(hexdec($firstOctet) | 0x01),
2,
'0',
STR_PAD_LEFT
);
$firstOctet = str_pad(dechex(hexdec($firstOctet) | 0x01), 2, '0', STR_PAD_LEFT);
return new Hexadecimal($firstOctet . substr($nodeHex, 2));
}
src/Provider/Node/SystemNodeProvider.php
+37 -42
View File
@@ -39,13 +39,12 @@ use const PREG_PATTERN_ORDER;
/**
* SystemNodeProvider retrieves the system node ID, if possible
*
* The system node ID, or host ID, is often the same as the MAC address for a
* network interface on the host.
* The system node ID, or host ID, is often the same as the MAC address for a network interface on the host.
*/
class SystemNodeProvider implements NodeProviderInterface
{
/**
* Pattern to match nodes in ifconfig and ipconfig output.
* Pattern to match nodes in `ifconfig` and `ipconfig` output.
*/
private const IFCONFIG_PATTERN = '/[^:]([0-9a-f]{2}([:-])[0-9a-f]{2}(\2[0-9a-f]{2}){4})[^:]/i';
@@ -59,16 +58,14 @@ class SystemNodeProvider implements NodeProviderInterface
$node = $this->getNodeFromSystem();
if ($node === '') {
throw new NodeException(
'Unable to fetch a node for this system'
);
throw new NodeException('Unable to fetch a node for this system');
}
return new Hexadecimal($node);
}
/**
* Returns the system node, if it can find it
* Returns the system node if found
*/
protected function getNodeFromSystem(): string
{
@@ -99,9 +96,7 @@ class SystemNodeProvider implements NodeProviderInterface
*/
protected function getIfconfig(): string
{
$disabledFunctions = strtolower((string) ini_get('disable_functions'));
if (str_contains($disabledFunctions, 'passthru')) {
if (str_contains(strtolower((string) ini_get('disable_functions')), 'passthru')) {
return '';
}
@@ -147,43 +142,43 @@ class SystemNodeProvider implements NodeProviderInterface
*/
protected function getSysfs(): string
{
$mac = '';
/** @var string $phpOs */
$phpOs = constant('PHP_OS');
if (strtoupper($phpOs) === 'LINUX') {
$addressPaths = glob('/sys/class/net/*/address', GLOB_NOSORT);
if ($addressPaths === false || count($addressPaths) === 0) {
return '';
}
/** @var array<array-key, string> $macs */
$macs = [];
array_walk($addressPaths, function (string $addressPath) use (&$macs): void {
if (is_readable($addressPath)) {
$macs[] = file_get_contents($addressPath);
}
});
/** @var callable $trim */
$trim = 'trim';
$macs = array_map($trim, $macs);
// Remove invalid entries.
$macs = array_filter($macs, function (mixed $address): bool {
assert(is_string($address));
return $address !== '00:00:00:00:00:00' && preg_match(self::SYSFS_PATTERN, $address);
});
/** @var string|bool $mac */
$mac = reset($macs);
if (strtoupper($phpOs) !== 'LINUX') {
return '';
}
$addressPaths = glob('/sys/class/net/*/address', GLOB_NOSORT);
if ($addressPaths === false || count($addressPaths) === 0) {
return '';
}
/** @var array<array-key, string> $macs */
$macs = [];
array_walk($addressPaths, function (string $addressPath) use (&$macs): void {
if (is_readable($addressPath)) {
$macs[] = file_get_contents($addressPath);
}
});
/** @var callable $trim */
$trim = 'trim';
$macs = array_map($trim, $macs);
// Remove invalid entries.
$macs = array_filter($macs, function (mixed $address): bool {
assert(is_string($address));
return $address !== '00:00:00:00:00:00' && preg_match(self::SYSFS_PATTERN, $address);
});
/** @var bool | string $mac */
$mac = reset($macs);
return (string) $mac;
}
}
src/Provider/Time/FixedTimeProvider.php
+3 -4
View File
@@ -21,8 +21,7 @@ use Ramsey\Uuid\Type\Time;
/**
* FixedTimeProvider uses a known time to provide the time
*
* This provider allows the use of a previously-generated, or known, time
* when generating time-based UUIDs.
* This provider allows the use of a previously generated, or known, time when generating time-based UUIDs.
*/
class FixedTimeProvider implements TimeProviderInterface
{
@@ -33,7 +32,7 @@ class FixedTimeProvider implements TimeProviderInterface
/**
* Sets the `usec` component of the time
*
* @param int|string|IntegerObject $value The `usec` value to set
* @param IntegerObject | int | string $value The `usec` value to set
*/
public function setUsec($value): void
{
@@ -43,7 +42,7 @@ class FixedTimeProvider implements TimeProviderInterface
/**
* Sets the `sec` component of the time
*
* @param int|string|IntegerObject $value The `sec` value to set
* @param IntegerObject | int | string $value The `sec` value to set
*/
public function setSec($value): void
{
src/Rfc4122/Fields.php
+17 -25
View File
@@ -31,10 +31,9 @@ use function unpack;
use const STR_PAD_LEFT;
/**
* RFC 4122 variant UUIDs consist of a set of named fields
* RFC 9562 (formerly RFC 4122) variant UUIDs consist of a set of named fields
*
* Internally, this class represents the fields together as a 16-byte binary
* string.
* Internally, this class represents the fields together as a 16-byte binary string.
*
* @immutable
*/
@@ -50,27 +49,26 @@ final class Fields implements FieldsInterface
* @param string $bytes A 16-byte binary string representation of a UUID
*
* @throws InvalidArgumentException if the byte string is not exactly 16 bytes
* @throws InvalidArgumentException if the byte string does not represent an RFC 4122 UUID
* @throws InvalidArgumentException if the byte string does not represent an RFC 9562 (formerly RFC 4122) UUID
* @throws InvalidArgumentException if the byte string does not contain a valid version
*/
public function __construct(private string $bytes)
{
if (strlen($this->bytes) !== 16) {
throw new InvalidArgumentException(
'The byte string must be 16 bytes long; '
. 'received ' . strlen($this->bytes) . ' bytes'
'The byte string must be 16 bytes long; ' . 'received ' . strlen($this->bytes) . ' bytes',
);
}
if (!$this->isCorrectVariant()) {
throw new InvalidArgumentException(
'The byte string received does not conform to the RFC 4122 variant'
'The byte string received does not conform to the RFC 9562 (formerly RFC 4122) variant',
);
}
if (!$this->isCorrectVersion()) {
throw new InvalidArgumentException(
'The byte string received does not contain a valid RFC 4122 version'
'The byte string received does not contain a valid RFC 9562 (formerly RFC 4122) version',
);
}
}
@@ -126,21 +124,18 @@ final class Fields implements FieldsInterface
/**
* Returns the full 60-bit timestamp, without the version
*
* For version 2 UUIDs, the time_low field is the local identifier and
* should not be returned as part of the time. For this reason, we set the
* bottom 32 bits of the timestamp to 0's. As a result, there is some loss
* of fidelity of the timestamp, for version 2 UUIDs. The timestamp can be
* off by a range of 0 to 429.4967295 seconds (or 7 minutes, 9 seconds, and
* 496730 microseconds).
* For version 2 UUIDs, the time_low field is the local identifier and should not be returned as part of the time.
* For this reason, we set the bottom 32 bits of the timestamp to 0's. As a result, there is some loss of timestamp
* fidelity, for version 2 UUIDs. The timestamp can be off by a range of 0 to 429.4967295 seconds (or 7 minutes, 9
* seconds, and 496,730 microseconds).
*
* For version 6 UUIDs, the timestamp order is reversed from the typical RFC
* 4122 order (the time bits are in the correct bit order, so that it is
* monotonically increasing). In returning the timestamp value, we put the
* bits in the order: time_low + time_mid + time_hi.
* For version 6 UUIDs, the timestamp order is reversed from the typical RFC 9562 (formerly RFC 4122) order (the
* time bits are in the correct bit order, so that it is monotonically increasing). In returning the timestamp
* value, we put the bits in the order: time_low + time_mid + time_hi.
*/
public function getTimestamp(): Hexadecimal
{
$timestamp = match ($this->getVersion()) {
return new Hexadecimal(match ($this->getVersion()) {
Uuid::UUID_TYPE_DCE_SECURITY => sprintf(
'%03x%04s%08s',
hexdec($this->getTimeHiAndVersion()->toString()) & 0x0fff,
@@ -153,9 +148,8 @@ final class Fields implements FieldsInterface
$this->getTimeMid()->toString(),
hexdec($this->getTimeHiAndVersion()->toString()) & 0x0fff
),
// The Unix timestamp in version 7 UUIDs is a 48-bit number,
// but for consistency, we will return a 60-bit number, padded
// to the left with zeros.
// The Unix timestamp in version 7 UUIDs is a 48-bit number, but for consistency, we will return a 60-bit
// number, padded to the left with zeros.
Uuid::UUID_TYPE_UNIX_TIME => sprintf(
'%011s%04s',
$this->getTimeLow()->toString(),
@@ -167,9 +161,7 @@ final class Fields implements FieldsInterface
$this->getTimeMid()->toString(),
$this->getTimeLow()->toString()
),
};
return new Hexadecimal($timestamp);
});
}
public function getVersion(): ?int
src/Rfc4122/FieldsInterface.php
+24 -26
View File
@@ -18,30 +18,30 @@ use Ramsey\Uuid\Fields\FieldsInterface as BaseFieldsInterface;
use Ramsey\Uuid\Type\Hexadecimal;
/**
* RFC 4122 defines fields for a specific variant of UUID
* UUID fields, as defined by RFC 4122
*
* This interface defines the fields of an RFC 4122 variant UUID. Since RFC 9562 removed the concept of fields and
* instead defined layouts that are specific to a given version, this interface is a legacy artifact of the earlier, and
* now obsolete, RFC 4122.
*
* The fields of an RFC 4122 variant UUID are:
*
* * **time_low**: The low field of the timestamp, an unsigned 32-bit integer
* * **time_mid**: The middle field of the timestamp, an unsigned 16-bit integer
* * **time_hi_and_version**: The high field of the timestamp multiplexed with
* the version number, an unsigned 16-bit integer
* * **clock_seq_hi_and_reserved**: The high field of the clock sequence
* multiplexed with the variant, an unsigned 8-bit integer
* * **clock_seq_low**: The low field of the clock sequence, an unsigned
* 8-bit integer
* * **node**: The spatially unique node identifier, an unsigned 48-bit
* integer
* * **time_hi_and_version**: The high field of the timestamp multiplexed with the version number, an unsigned 16-bit integer
* * **clock_seq_hi_and_reserved**: The high field of the clock sequence multiplexed with the variant, an unsigned 8-bit integer
* * **clock_seq_low**: The low field of the clock sequence, an unsigned 8-bit integer
* * **node**: The spatially unique node identifier, an unsigned 48-bit integer
*
* @link http://tools.ietf.org/html/rfc4122#section-4.1 RFC 4122, § 4.1: Format
* @link https://www.rfc-editor.org/rfc/rfc4122#section-4.1 RFC 4122, 4.1. Format
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4 RFC 9562, 4. UUID Format
*
* @immutable
*/
interface FieldsInterface extends BaseFieldsInterface
{
/**
* Returns the full 16-bit clock sequence, with the variant bits (two most
* significant bits) masked out
* Returns the full 16-bit clock sequence, with the variant bits (two most significant bits) masked out
*/
public function getClockSeq(): Hexadecimal;
@@ -83,46 +83,44 @@ interface FieldsInterface extends BaseFieldsInterface
/**
* Returns the variant
*
* The variant number describes the layout of the UUID. The variant
* number has the following meaning:
* The variant number describes the layout of the UUID. The variant number has the following meaning:
*
* - 0 - Reserved for NCS backward compatibility
* - 2 - The RFC 4122 variant
* - 2 - The RFC 9562 (formerly RFC 4122) variant
* - 6 - Reserved, Microsoft Corporation backward compatibility
* - 7 - Reserved for future definition
*
* For RFC 4122 variant UUIDs, this value should always be the integer `2`.
* For RFC 9562 (formerly RFC 4122) variant UUIDs, this value should always be the integer `2`.
*
* @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
*/
public function getVariant(): int;
/**
* Returns the version
* Returns the UUID version
*
* The version number describes how the UUID was generated and has the
* following meaning:
* The version number describes how the UUID was generated and has the following meaning:
*
* 1. Gregorian time UUID
* 2. DCE security UUID
* 3. Name-based UUID hashed with MD5
* 4. Randomly generated UUID
* 5. Name-based UUID hashed with SHA-1
* 6. Reordered time UUID
* 6. Reordered Gregorian time UUID
* 7. Unix Epoch time UUID
* 8. Custom format UUID
*
* This returns `null` if the UUID is not an RFC 4122 variant, since version
* is only meaningful for this variant.
* This returns `null` if the UUID is not an RFC 9562 (formerly RFC 4122) variant, since the version is only
* meaningful for this variant.
*
* @link http://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
*/
public function getVersion(): ?int;
/**
* Returns true if these fields represent a nil UUID
*
* The nil UUID is special form of UUID that is specified to have all 128
* bits set to zero.
* The nil UUID is a special form of UUID that is specified to have all 128 bits set to zero.
*/
public function isNil(): bool;
}
src/Rfc4122/MaxTrait.php
-5
View File
@@ -17,11 +17,6 @@ namespace Ramsey\Uuid\Rfc4122;
/**
* Provides common functionality for max UUIDs
*
* The max UUID is special form of UUID that is specified to have all 128 bits
* set to one. It is the inverse of the nil UUID.
*
* @link https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis-00#section-5.10 Max UUID
*
* @immutable
*/
trait MaxTrait
src/Rfc4122/MaxUuid.php
+3 -2
View File
@@ -17,8 +17,9 @@ namespace Ramsey\Uuid\Rfc4122;
use Ramsey\Uuid\Uuid;
/**
* The max UUID is special form of UUID that is specified to have all 128 bits
* set to one
* The max UUID is a special form of UUID that has all 128 bits set to one (`1`)
*
* @link https://www.rfc-editor.org/rfc/rfc9562#section-5.10 RFC 9562, 5.10. Max UUID
*
* @immutable
*/
src/Rfc4122/NilTrait.php
-5
View File
@@ -17,11 +17,6 @@ namespace Ramsey\Uuid\Rfc4122;
/**
* Provides common functionality for nil UUIDs
*
* The nil UUID is special form of UUID that is specified to have all 128 bits
* set to zero.
*
* @link https://tools.ietf.org/html/rfc4122#section-4.1.7 RFC 4122, § 4.1.7: Nil UUID
*
* @immutable
*/
trait NilTrait
src/Rfc4122/NilUuid.php
+3 -2
View File
@@ -17,8 +17,9 @@ namespace Ramsey\Uuid\Rfc4122;
use Ramsey\Uuid\Uuid;
/**
* The nil UUID is special form of UUID that is specified to have all 128 bits
* set to zero
* The nil UUID is a special form of UUID that has all 128 bits set to zero (`0`)
*
* @link https://www.rfc-editor.org/rfc/rfc9562#section-5.9 RFC 9562, 5.9. Nil UUID
*
* @immutable
*/
src/Rfc4122/TimeTrait.php
+2 -4
View File
@@ -31,11 +31,9 @@ use const STR_PAD_LEFT;
trait TimeTrait
{
/**
* Returns a DateTimeInterface object representing the timestamp associated
* with the UUID
* Returns a DateTimeInterface object representing the timestamp associated with the UUID
*
* @return DateTimeImmutable A PHP DateTimeImmutable instance representing
* the timestamp of a time-based UUID
* @return DateTimeImmutable A PHP DateTimeImmutable instance representing the timestamp of a time-based UUID
*/
public function getDateTime(): DateTimeInterface
{
src/Rfc4122/UuidBuilder.php
+23 -33
View File
@@ -28,7 +28,7 @@ use Ramsey\Uuid\UuidInterface;
use Throwable;
/**
* UuidBuilder builds instances of RFC 4122 UUIDs
* UuidBuilder builds instances of RFC 9562 (formerly 4122) UUIDs
*
* @immutable
*/
@@ -39,14 +39,11 @@ class UuidBuilder implements UuidBuilderInterface
/**
* Constructs the DefaultUuidBuilder
*
* @param NumberConverterInterface $numberConverter The number converter to
* use when constructing the Uuid
* @param TimeConverterInterface $timeConverter The time converter to use
* for converting Gregorian time extracted from version 1, 2, and 6
* UUIDs to Unix timestamps
* @param TimeConverterInterface|null $unixTimeConverter The time converter
* to use for converter Unix Epoch time extracted from version 7 UUIDs
* to Unix timestamps
* @param NumberConverterInterface $numberConverter The number converter to use when constructing the Uuid
* @param TimeConverterInterface $timeConverter The time converter to use for converting Gregorian time extracted
* from version 1, 2, and 6 UUIDs to Unix timestamps
* @param TimeConverterInterface|null $unixTimeConverter The time converter to use for converter Unix Epoch time
* extracted from version 7 UUIDs to Unix timestamps
*/
public function __construct(
private NumberConverterInterface $numberConverter,
@@ -78,36 +75,29 @@ class UuidBuilder implements UuidBuilderInterface
return new MaxUuid($fields, $this->numberConverter, $codec, $this->timeConverter);
}
switch ($fields->getVersion()) {
case Uuid::UUID_TYPE_TIME:
return new UuidV1($fields, $this->numberConverter, $codec, $this->timeConverter);
case Uuid::UUID_TYPE_DCE_SECURITY:
return new UuidV2($fields, $this->numberConverter, $codec, $this->timeConverter);
case Uuid::UUID_TYPE_HASH_MD5:
return new UuidV3($fields, $this->numberConverter, $codec, $this->timeConverter);
case Uuid::UUID_TYPE_RANDOM:
return new UuidV4($fields, $this->numberConverter, $codec, $this->timeConverter);
case Uuid::UUID_TYPE_HASH_SHA1:
return new UuidV5($fields, $this->numberConverter, $codec, $this->timeConverter);
case Uuid::UUID_TYPE_REORDERED_TIME:
return new UuidV6($fields, $this->numberConverter, $codec, $this->timeConverter);
case Uuid::UUID_TYPE_UNIX_TIME:
return new UuidV7($fields, $this->numberConverter, $codec, $this->unixTimeConverter);
case Uuid::UUID_TYPE_CUSTOM:
return new UuidV8($fields, $this->numberConverter, $codec, $this->timeConverter);
}
throw new UnsupportedOperationException(
'The UUID version in the given fields is not supported '
. 'by this UUID builder'
);
return match ($fields->getVersion()) {
Uuid::UUID_TYPE_TIME => new UuidV1($fields, $this->numberConverter, $codec, $this->timeConverter),
Uuid::UUID_TYPE_DCE_SECURITY
=> new UuidV2($fields, $this->numberConverter, $codec, $this->timeConverter),
Uuid::UUID_TYPE_HASH_MD5 => new UuidV3($fields, $this->numberConverter, $codec, $this->timeConverter),
Uuid::UUID_TYPE_RANDOM => new UuidV4($fields, $this->numberConverter, $codec, $this->timeConverter),
Uuid::UUID_TYPE_HASH_SHA1 => new UuidV5($fields, $this->numberConverter, $codec, $this->timeConverter),
Uuid::UUID_TYPE_REORDERED_TIME
=> new UuidV6($fields, $this->numberConverter, $codec, $this->timeConverter),
Uuid::UUID_TYPE_UNIX_TIME
=> new UuidV7($fields, $this->numberConverter, $codec, $this->unixTimeConverter),
Uuid::UUID_TYPE_CUSTOM => new UuidV8($fields, $this->numberConverter, $codec, $this->timeConverter),
default => throw new UnsupportedOperationException(
'The UUID version in the given fields is not supported by this UUID builder',
),
};
} catch (Throwable $e) {
throw new UnableToBuildUuidException($e->getMessage(), (int) $e->getCode(), $e);
}
}
/**
* Proxy method to allow injecting a mock, for testing
* Proxy method to allow injecting a mock for testing
*/
protected function buildFields(string $bytes): FieldsInterface
{
src/Rfc4122/UuidInterface.php
+2 -3
View File
@@ -17,10 +17,9 @@ namespace Ramsey\Uuid\Rfc4122;
use Ramsey\Uuid\UuidInterface as BaseUuidInterface;
/**
* Also known as a Leach-Salz variant UUID, an RFC 4122 variant UUID is a
* universally unique identifier defined by RFC 4122
* A universally unique identifier (UUID), as defined in RFC 9562 (formerly RFC 4122)
*
* @link https://tools.ietf.org/html/rfc4122 RFC 4122
* @link https://www.rfc-editor.org/rfc/rfc9562 RFC 9562
*
* @immutable
*/
src/Rfc4122/UuidV1.php
+9 -11
View File
@@ -22,8 +22,9 @@ use Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface;
use Ramsey\Uuid\Uuid;
/**
* Gregorian time, or version 1, UUIDs include timestamp, clock sequence, and node
* values that are combined into a 128-bit unsigned integer
* Gregorian time, or version 1, UUIDs include timestamp, clock sequence, and node values, combined into a 128-bit unsigned integer
*
* @link https://www.rfc-editor.org/rfc/rfc9562#section-5.1 RFC 9562, 5.1. UUID Version 1
*
* @immutable
*/
@@ -35,23 +36,20 @@ final class UuidV1 extends Uuid implements UuidInterface
* Creates a version 1 (Gregorian time) UUID
*
* @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID
* @param NumberConverterInterface $numberConverter The number converter to use
* for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding
* UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use
* for converting timestamps extracted from a UUID to unix timestamps
* @param NumberConverterInterface $numberConverter The number converter to use for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a
* UUID to unix timestamps
*/
public function __construct(
Rfc4122FieldsInterface $fields,
NumberConverterInterface $numberConverter,
CodecInterface $codec,
TimeConverterInterface $timeConverter
TimeConverterInterface $timeConverter,
) {
if ($fields->getVersion() !== Uuid::UUID_TYPE_TIME) {
throw new InvalidArgumentException(
'Fields used to create a UuidV1 must represent a '
. 'version 1 (time-based) UUID'
'Fields used to create a UuidV1 must represent a version 1 (time-based) UUID',
);
}
src/Rfc4122/UuidV2.php
+17 -25
View File
@@ -25,22 +25,19 @@ use Ramsey\Uuid\Uuid;
use function hexdec;
/**
* DCE Security version, or version 2, UUIDs include local domain identifier,
* local ID for the specified domain, and node values that are combined into a
* 128-bit unsigned integer
* DCE Security version, or version 2, UUIDs include local domain identifier, local ID for the specified domain, and
* node values that are combined into a 128-bit unsigned integer
*
* It is important to note that a version 2 UUID suffers from some loss of
* fidelity of the timestamp, due to replacing the time_low field with the
* local identifier. When constructing the timestamp value for date
* purposes, we replace the local identifier bits with zeros. As a result,
* the timestamp can be off by a range of 0 to 429.4967295 seconds (or 7
* minutes, 9 seconds, and 496730 microseconds).
* It is important to note that a version 2 UUID suffers from some loss of timestamp fidelity, due to replacing the
* time_low field with the local identifier. When constructing the timestamp value for date purposes, we replace the
* local identifier bits with zeros. As a result, the timestamp can be off by a range of 0 to 429.4967295 seconds (or 7
* minutes, 9 seconds, and 496,730 microseconds).
*
* Astute observers might note this value directly corresponds to 2^32 - 1,
* or 0xffffffff. The local identifier is 32-bits, and we have set each of
* these bits to 0, so the maximum range of timestamp drift is 0x00000000
* to 0xffffffff (counted in 100-nanosecond intervals).
* Astute observers might note this value directly corresponds to `2^32-1`, or `0xffffffff`. The local identifier is
* 32-bits, and we have set each of these bits to `0`, so the maximum range of timestamp drift is `0x00000000` to
* `0xffffffff` (counted in 100-nanosecond intervals).
*
* @link https://www.rfc-editor.org/rfc/rfc9562#section-5.2 RFC 9562, 5.2. UUID Version 2
* @link https://publications.opengroup.org/c311 DCE 1.1: Authentication and Security Services
* @link https://publications.opengroup.org/c706 DCE 1.1: Remote Procedure Call
* @link https://pubs.opengroup.org/onlinepubs/9696989899/chap5.htm#tagcjh_08_02_01_01 DCE 1.1: Auth & Sec, §5.2.1.1
@@ -58,23 +55,20 @@ final class UuidV2 extends Uuid implements UuidInterface
* Creates a version 2 (DCE Security) UUID
*
* @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID
* @param NumberConverterInterface $numberConverter The number converter to use
* for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding
* UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use
* for converting timestamps extracted from a UUID to unix timestamps
* @param NumberConverterInterface $numberConverter The number converter to use for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a
* UUID to unix timestamps
*/
public function __construct(
Rfc4122FieldsInterface $fields,
NumberConverterInterface $numberConverter,
CodecInterface $codec,
TimeConverterInterface $timeConverter
TimeConverterInterface $timeConverter,
) {
if ($fields->getVersion() !== Uuid::UUID_TYPE_DCE_SECURITY) {
throw new InvalidArgumentException(
'Fields used to create a UuidV2 must represent a '
. 'version 2 (DCE Security) UUID'
'Fields used to create a UuidV2 must represent a version 2 (DCE Security) UUID'
);
}
@@ -108,8 +102,6 @@ final class UuidV2 extends Uuid implements UuidInterface
/** @var Rfc4122FieldsInterface $fields */
$fields = $this->getFields();
return new IntegerObject(
$this->numberConverter->fromHex($fields->getTimeLow()->toString())
);
return new IntegerObject($this->numberConverter->fromHex($fields->getTimeLow()->toString()));
}
}
src/Rfc4122/UuidV3.php
+10 -11
View File
@@ -22,8 +22,10 @@ use Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface;
use Ramsey\Uuid\Uuid;
/**
* Version 3 UUIDs are named-based, using a combination of a namespace and name
* that are hashed into a 128-bit unsigned integer using MD5
* Version 3 UUIDs are named-based, using a combination of a namespace and name that are hashed into a 128-bit unsigned
* integer using the MD5 hashing algorithm
*
* @link https://www.rfc-editor.org/rfc/rfc9562#section-5.3 RFC 9562, 5.3. UUID Version 3
*
* @immutable
*/
@@ -33,23 +35,20 @@ final class UuidV3 extends Uuid implements UuidInterface
* Creates a version 3 (name-based, MD5-hashed) UUID
*
* @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID
* @param NumberConverterInterface $numberConverter The number converter to use
* for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding
* UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use
* for converting timestamps extracted from a UUID to unix timestamps
* @param NumberConverterInterface $numberConverter The number converter to use for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a
* UUID to unix timestamps
*/
public function __construct(
Rfc4122FieldsInterface $fields,
NumberConverterInterface $numberConverter,
CodecInterface $codec,
TimeConverterInterface $timeConverter
TimeConverterInterface $timeConverter,
) {
if ($fields->getVersion() !== Uuid::UUID_TYPE_HASH_MD5) {
throw new InvalidArgumentException(
'Fields used to create a UuidV3 must represent a '
. 'version 3 (name-based, MD5-hashed) UUID'
'Fields used to create a UuidV3 must represent a version 3 (name-based, MD5-hashed) UUID',
);
}
src/Rfc4122/UuidV4.php
+9 -11
View File
@@ -22,8 +22,9 @@ use Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface;
use Ramsey\Uuid\Uuid;
/**
* Random, or version 4, UUIDs are randomly or pseudo-randomly generated 128-bit
* integers
* Random, or version 4, UUIDs are randomly or pseudo-randomly generated 128-bit integers
*
* @link https://www.rfc-editor.org/rfc/rfc9562#section-5.4 RFC 9562, 5.4. UUID Version 4
*
* @immutable
*/
@@ -33,23 +34,20 @@ final class UuidV4 extends Uuid implements UuidInterface
* Creates a version 4 (random) UUID
*
* @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID
* @param NumberConverterInterface $numberConverter The number converter to use
* for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding
* UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use
* for converting timestamps extracted from a UUID to unix timestamps
* @param NumberConverterInterface $numberConverter The number converter to use for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a
* UUID to unix timestamps
*/
public function __construct(
Rfc4122FieldsInterface $fields,
NumberConverterInterface $numberConverter,
CodecInterface $codec,
TimeConverterInterface $timeConverter
TimeConverterInterface $timeConverter,
) {
if ($fields->getVersion() !== Uuid::UUID_TYPE_RANDOM) {
throw new InvalidArgumentException(
'Fields used to create a UuidV4 must represent a '
. 'version 4 (random) UUID'
'Fields used to create a UuidV4 must represent a version 4 (random) UUID',
);
}
src/Rfc4122/UuidV5.php
+10 -11
View File
@@ -22,8 +22,10 @@ use Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface;
use Ramsey\Uuid\Uuid;
/**
* Version 5 UUIDs are named-based, using a combination of a namespace and name
* that are hashed into a 128-bit unsigned integer using SHA1
* Version 5 UUIDs are named-based, using a combination of a namespace and name that are hashed into a 128-bit unsigned
* integer using the SHA1 hashing algorithm
*
* @link https://www.rfc-editor.org/rfc/rfc9562#section-5.5 RFC 9562, 5.5. UUID Version 5
*
* @immutable
*/
@@ -33,23 +35,20 @@ final class UuidV5 extends Uuid implements UuidInterface
* Creates a version 5 (name-based, SHA1-hashed) UUID
*
* @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID
* @param NumberConverterInterface $numberConverter The number converter to use
* for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding
* UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use
* for converting timestamps extracted from a UUID to unix timestamps
* @param NumberConverterInterface $numberConverter The number converter to use for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a
* UUID to unix timestamps
*/
public function __construct(
Rfc4122FieldsInterface $fields,
NumberConverterInterface $numberConverter,
CodecInterface $codec,
TimeConverterInterface $timeConverter
TimeConverterInterface $timeConverter,
) {
if ($fields->getVersion() !== Uuid::UUID_TYPE_HASH_SHA1) {
throw new InvalidArgumentException(
'Fields used to create a UuidV5 must represent a '
. 'version 5 (named-based, SHA1-hashed) UUID'
'Fields used to create a UuidV5 must represent a version 5 (named-based, SHA1-hashed) UUID',
);
}
src/Rfc4122/UuidV6.php
+3 -3
View File
@@ -17,10 +17,10 @@ namespace Ramsey\Uuid\Rfc4122;
use Ramsey\Uuid\Nonstandard\UuidV6 as NonstandardUuidV6;
/**
* Reordered time, or version 6, UUIDs include timestamp, clock sequence, and
* node values that are combined into a 128-bit unsigned integer
* Reordered Gregorian time, or version 6, UUIDs include timestamp, clock sequence, and node values that are combined
* into a 128-bit unsigned integer
*
* @link https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis-00#section-5.6 UUID Version 6
* @link https://www.rfc-editor.org/rfc/rfc9562#section-5.6 RFC 9562, 5.6. UUID Version 6
*
* @immutable
*/
src/Rfc4122/UuidV7.php
+8 -12
View File
@@ -22,10 +22,9 @@ use Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface;
use Ramsey\Uuid\Uuid;
/**
* Unix Epoch time, or version 7, UUIDs include a timestamp in milliseconds
* since the Unix Epoch, along with random bytes
* Unix Epoch time, or version 7, UUIDs include a timestamp in milliseconds since the Unix Epoch, along with random bytes
*
* @link https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis-00#section-5.7 UUID Version 7
* @link https://www.rfc-editor.org/rfc/rfc9562#section-5.7 RFC 9562, 5.7. UUID Version 7
*
* @immutable
*/
@@ -37,23 +36,20 @@ final class UuidV7 extends Uuid implements UuidInterface
* Creates a version 7 (Unix Epoch time) UUID
*
* @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID
* @param NumberConverterInterface $numberConverter The number converter to use
* for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding
* UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use
* for converting timestamps extracted from a UUID to unix timestamps
* @param NumberConverterInterface $numberConverter The number converter to use for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a
* UUID to unix timestamps
*/
public function __construct(
Rfc4122FieldsInterface $fields,
NumberConverterInterface $numberConverter,
CodecInterface $codec,
TimeConverterInterface $timeConverter
TimeConverterInterface $timeConverter,
) {
if ($fields->getVersion() !== Uuid::UUID_TYPE_UNIX_TIME) {
throw new InvalidArgumentException(
'Fields used to create a UuidV7 must represent a '
. 'version 7 (Unix Epoch time) UUID'
'Fields used to create a UuidV7 must represent a version 7 (Unix Epoch time) UUID',
);
}
src/Rfc4122/UuidV8.php
+11 -16
View File
@@ -22,41 +22,36 @@ use Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface;
use Ramsey\Uuid\Uuid;
/**
* Version 8, Custom UUIDs provide an RFC 4122 compatible format for
* experimental or vendor-specific uses
* Custom format, or version 8, UUIDs provide an RFC-compatible format for experimental or vendor-specific uses
*
* The only requirement for version 8 UUIDs is that the version and variant bits
* must be set. Otherwise, implementations are free to set the other bits
* according to their needs. As a result, the uniqueness of version 8 UUIDs is
* The only requirement for version 8 UUIDs is that the version and variant bits must be set. Otherwise, implementations
* are free to set the other bits according to their needs. As a result, the uniqueness of version 8 UUIDs is
* implementation-specific and should not be assumed.
*
* @link https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis-00#section-5.8 UUID Version 8
* @link https://www.rfc-editor.org/rfc/rfc9562#section-5.8 RFC 9562, 5.8. UUID Version 8
*
* @immutable
*/
final class UuidV8 extends Uuid implements UuidInterface
{
/**
* Creates a version 8 (custom) UUID
* Creates a version 8 (custom format) UUID
*
* @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID
* @param NumberConverterInterface $numberConverter The number converter to use
* for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding
* UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use
* for converting timestamps extracted from a UUID to unix timestamps
* @param NumberConverterInterface $numberConverter The number converter to use for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a
* UUID to unix timestamps
*/
public function __construct(
Rfc4122FieldsInterface $fields,
NumberConverterInterface $numberConverter,
CodecInterface $codec,
TimeConverterInterface $timeConverter
TimeConverterInterface $timeConverter,
) {
if ($fields->getVersion() !== Uuid::UUID_TYPE_CUSTOM) {
throw new InvalidArgumentException(
'Fields used to create a UuidV8 must represent a '
. 'version 8 (custom) UUID'
'Fields used to create a UuidV8 must represent a version 8 (custom format) UUID',
);
}
src/Rfc4122/Validator.php
+2 -3
View File
@@ -21,7 +21,7 @@ use function preg_match;
use function str_replace;
/**
* Rfc4122\Validator validates strings as UUIDs of the RFC 4122 variant
* Rfc4122\Validator validates strings as UUIDs of the RFC 9562 (formerly RFC 4122) variant
*
* @immutable
*/
@@ -40,8 +40,7 @@ final class Validator implements ValidatorInterface
public function validate(string $uuid): bool
{
$uuid = str_replace(['urn:', 'uuid:', 'URN:', 'UUID:', '{', '}'], '', $uuid);
$uuid = strtolower($uuid);
$uuid = strtolower(str_replace(['urn:', 'uuid:', 'URN:', 'UUID:', '{', '}'], '', $uuid));
return $uuid === Uuid::NIL || $uuid === Uuid::MAX || preg_match('/' . self::VALID_PATTERN . '/Dms', $uuid);
}
src/Rfc4122/VariantTrait.php
+13 -24
View File
@@ -27,7 +27,7 @@ use function unpack;
use const STR_PAD_LEFT;
/**
* Provides common functionality for handling the variant, as defined by RFC 4122
* Provides common functionality for handling the variant, as defined by RFC 9562 (formerly RFC 4122)
*
* @immutable
*/
@@ -39,18 +39,18 @@ trait VariantTrait
abstract public function getBytes(): string;
/**
* Returns the variant identifier, according to RFC 4122, for the given bytes
* Returns the variant
*
* The following values may be returned:
* The variant number describes the layout of the UUID. The variant number has the following meaning:
*
* - `0` -- Reserved, NCS backward compatibility.
* - `2` -- The variant specified in RFC 4122.
* - `6` -- Reserved, Microsoft Corporation backward compatibility.
* - `7` -- Reserved for future definition.
* - 0 - Reserved for NCS backward compatibility
* - 2 - The RFC 9562 (formerly RFC 4122) variant
* - 6 - Reserved, Microsoft Corporation backward compatibility
* - 7 - Reserved for future definition
*
* @link https://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant
* For RFC 9562 (formerly RFC 4122) variant UUIDs, this value should always be the integer `2`.
*
* @return int The variant identifier, according to RFC 4122
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
*/
public function getVariant(): int
{
@@ -59,27 +59,16 @@ trait VariantTrait
}
if ($this->isMax() || $this->isNil()) {
// RFC 4122 defines these special types of UUID, so we will consider
// them as belonging to the RFC 4122 variant.
return Uuid::RFC_4122;
}
/** @var int[] $parts */
$parts = unpack('n*', $this->getBytes());
// $parts[5] is a 16-bit, unsigned integer containing the variant bits
// of the UUID. We convert this integer into a string containing a
// binary representation, padded to 16 characters. We analyze the first
// three characters (three most-significant bits) to determine the
// variant.
$binary = str_pad(
decbin($parts[5]),
16,
'0',
STR_PAD_LEFT
);
$msb = substr($binary, 0, 3);
// $parts[5] is a 16-bit, unsigned integer containing the variant bits of the UUID. We convert this integer into
// a string containing a binary representation, padded to 16 characters. We analyze the first three characters
// (three most-significant bits) to determine the variant.
$msb = substr(str_pad(decbin($parts[5]), 16, '0', STR_PAD_LEFT), 0, 3);
if ($msb === '111') {
return Uuid::RESERVED_FUTURE;
src/Rfc4122/VersionTrait.php
+22 -6
View File
@@ -17,14 +17,30 @@ namespace Ramsey\Uuid\Rfc4122;
use Ramsey\Uuid\Uuid;
/**
* Provides common functionality for handling the version, as defined by RFC 4122
* Provides common functionality for handling the version, as defined by RFC 9562 (formerly RFC 4122)
*
* @immutable
*/
trait VersionTrait
{
/**
* Returns the version
* Returns the UUID version
*
* The version number describes how the UUID was generated and has the following meaning:
*
* 1. Gregorian time UUID
* 2. DCE security UUID
* 3. Name-based UUID hashed with MD5
* 4. Randomly generated UUID
* 5. Name-based UUID hashed with SHA-1
* 6. Reordered Gregorian time UUID
* 7. Unix Epoch time UUID
* 8. Custom format UUID
*
* This returns `null` if the UUID is not an RFC 9562 (formerly RFC 4122) variant, since the version is only
* meaningful for this variant.
*
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
*/
abstract public function getVersion(): ?int;
@@ -39,7 +55,7 @@ trait VersionTrait
abstract public function isNil(): bool;
/**
* Returns true if the version matches one of those defined by RFC 4122
* Returns true if the version matches one of those defined by RFC 9562 (formerly RFC 4122)
*
* @return bool True if the UUID version is valid, false otherwise
*/
@@ -51,9 +67,9 @@ trait VersionTrait
return match ($this->getVersion()) {
Uuid::UUID_TYPE_TIME, Uuid::UUID_TYPE_DCE_SECURITY,
Uuid::UUID_TYPE_HASH_MD5, Uuid::UUID_TYPE_RANDOM,
Uuid::UUID_TYPE_HASH_SHA1, Uuid::UUID_TYPE_REORDERED_TIME,
Uuid::UUID_TYPE_UNIX_TIME, Uuid::UUID_TYPE_CUSTOM => true,
Uuid::UUID_TYPE_HASH_MD5, Uuid::UUID_TYPE_RANDOM,
Uuid::UUID_TYPE_HASH_SHA1, Uuid::UUID_TYPE_REORDERED_TIME,
Uuid::UUID_TYPE_UNIX_TIME, Uuid::UUID_TYPE_CUSTOM => true,
default => false,
};
}
src/Type/Decimal.php
+3 -5
View File
@@ -24,12 +24,10 @@ use function str_starts_with;
/**
* A value object representing a decimal
*
* This class exists for type-safety purposes, to ensure that decimals
* returned from ramsey/uuid methods as strings are truly decimals and not some
* other kind of string.
* This class exists for type-safety purposes, to ensure that decimals returned from ramsey/uuid methods as strings are
* truly decimals and not some other kind of string.
*
* To support values as true decimals and not as floats or doubles, we store the
* decimals as strings.
* To support values as true decimals and not as floats or doubles, we store the decimals as strings.
*
* @immutable
*/
src/Type/Hexadecimal.php
+4 -7
View File
@@ -24,9 +24,8 @@ use function substr;
/**
* A value object representing a hexadecimal number
*
* This class exists for type-safety purposes, to ensure that hexadecimal numbers
* returned from ramsey/uuid methods as strings are truly hexadecimal and not some
* other kind of string.
* This class exists for type-safety purposes, to ensure that hexadecimal numbers returned from ramsey/uuid methods as
* strings are truly hexadecimal and not some other kind of string.
*
* @immutable
*/
@@ -38,7 +37,7 @@ final class Hexadecimal implements TypeInterface
private string $value;
/**
* @param self|string $value The hexadecimal value to store
* @param self | string $value The hexadecimal value to store
*/
public function __construct(self | string $value)
{
@@ -121,9 +120,7 @@ final class Hexadecimal implements TypeInterface
}
if (!preg_match('/^[A-Fa-f0-9]+$/', $value)) {
throw new InvalidArgumentException(
'Value must be a hexadecimal number'
);
throw new InvalidArgumentException('Value must be a hexadecimal number');
}
/** @var non-empty-string */
src/Type/Integer.php
+6 -7
View File
@@ -26,12 +26,11 @@ use function substr;
/**
* A value object representing an integer
*
* This class exists for type-safety purposes, to ensure that integers
* returned from ramsey/uuid methods as strings are truly integers and not some
* other kind of string.
* This class exists for type-safety purposes, to ensure that integers returned from ramsey/uuid methods as strings are
* truly integers and not some other kind of string.
*
* To support large integers beyond PHP_INT_MAX and PHP_INT_MIN on both 64-bit
* and 32-bit systems, we store the integers as strings.
* To support large integers beyond PHP_INT_MAX and PHP_INT_MIN on both 64-bit and 32-bit systems, we store the integers
* as strings.
*
* @immutable
*/
@@ -47,7 +46,7 @@ final class Integer implements NumberInterface
*/
private bool $isNegative = false;
public function __construct(float | int | string | self $value)
public function __construct(self | float | int | string $value)
{
$this->value = $value instanceof self ? (string) $value : $this->prepareValue($value);
}
@@ -123,7 +122,7 @@ final class Integer implements NumberInterface
$value = (string) $value;
$sign = '+';
// If the value contains a sign, remove it for digit pattern check.
// If the value contains a sign, remove it for the digit pattern check.
if (str_starts_with($value, '-') || str_starts_with($value, '+')) {
$sign = substr($value, 0, 1);
$value = substr($value, 1);
src/Type/Time.php
+6 -9
View File
@@ -25,9 +25,8 @@ use function sprintf;
/**
* A value object representing a timestamp
*
* This class exists for type-safety purposes, to ensure that timestamps used
* by ramsey/uuid are truly timestamp integers and not some other kind of string
* or integer.
* This class exists for type-safety purposes, to ensure that timestamps used by ramsey/uuid are truly timestamp
* integers and not some other kind of string or integer.
*
* @immutable
*/
@@ -37,8 +36,8 @@ final class Time implements TypeInterface
private IntegerObject $microseconds;
public function __construct(
float | int | string | IntegerObject $seconds,
float | int | string | IntegerObject $microseconds = 0,
IntegerObject | float | int | string $seconds,
IntegerObject | float | int | string $microseconds = 0,
) {
$this->seconds = new IntegerObject($seconds);
$this->microseconds = new IntegerObject($microseconds);
@@ -98,13 +97,11 @@ final class Time implements TypeInterface
*/
public function unserialize(string $data): void
{
/** @var array{seconds?: int|float|string, microseconds?: int|float|string} $time */
/** @var array{seconds?: float | int | string, microseconds?: float | int | string} $time */
$time = json_decode($data, true);
if (!isset($time['seconds']) || !isset($time['microseconds'])) {
throw new UnsupportedOperationException(
'Attempted to unserialize an invalid value'
);
throw new UnsupportedOperationException('Attempted to unserialize an invalid value');
}
$this->__construct($time['seconds'], $time['microseconds']);
src/Uuid.php
+94 -130
View File
@@ -49,76 +49,80 @@ class Uuid implements UuidInterface
use DeprecatedUuidMethodsTrait;
/**
* When this namespace is specified, the name string is a fully qualified
* domain name
* When this namespace is specified, the name string is a fully qualified domain name
*
* @link http://tools.ietf.org/html/rfc4122#appendix-C RFC 4122, Appendix C: Some Name Space IDs
* @link https://www.rfc-editor.org/rfc/rfc9562#section-6.6 RFC 9562, 6.6. Namespace ID Usage and Allocation
*/
public const NAMESPACE_DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
/**
* When this namespace is specified, the name string is a URL
*
* @link http://tools.ietf.org/html/rfc4122#appendix-C RFC 4122, Appendix C: Some Name Space IDs
* @link https://www.rfc-editor.org/rfc/rfc9562#section-6.6 RFC 9562, 6.6. Namespace ID Usage and Allocation
*/
public const NAMESPACE_URL = '6ba7b811-9dad-11d1-80b4-00c04fd430c8';
/**
* When this namespace is specified, the name string is an ISO OID
*
* @link http://tools.ietf.org/html/rfc4122#appendix-C RFC 4122, Appendix C: Some Name Space IDs
* @link https://www.rfc-editor.org/rfc/rfc9562#section-6.6 RFC 9562, 6.6. Namespace ID Usage and Allocation
*/
public const NAMESPACE_OID = '6ba7b812-9dad-11d1-80b4-00c04fd430c8';
/**
* When this namespace is specified, the name string is an X.500 DN in DER
* or a text output format
* When this namespace is specified, the name string is an X.500 DN (in DER or a text output format)
*
* @link http://tools.ietf.org/html/rfc4122#appendix-C RFC 4122, Appendix C: Some Name Space IDs
* @link https://www.rfc-editor.org/rfc/rfc9562#section-6.6 RFC 9562, 6.6. Namespace ID Usage and Allocation
*/
public const NAMESPACE_X500 = '6ba7b814-9dad-11d1-80b4-00c04fd430c8';
/**
* The nil UUID is a special form of UUID that is specified to have all 128
* bits set to zero
* The Nil UUID is a special form of UUID that is specified to have all 128 bits set to zero
*
* @link http://tools.ietf.org/html/rfc4122#section-4.1.7 RFC 4122, § 4.1.7: Nil UUID
* @link https://www.rfc-editor.org/rfc/rfc9562#section-5.9 RFC 9562, 5.9. Nil UUID
*/
public const NIL = '00000000-0000-0000-0000-000000000000';
/**
* The max UUID is a special form of UUID that is specified to have all 128
* bits set to one
* The Max UUID is a special form of UUID that is specified to have all 128 bits set to one
*
* @link https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis-00#section-5.10 Max UUID
* @link https://www.rfc-editor.org/rfc/rfc9562#section-5.10 RFC 9562, 5.10. Max UUID
*/
public const MAX = 'ffffffff-ffff-ffff-ffff-ffffffffffff';
/**
* Variant: reserved, NCS backward compatibility
*
* @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
*/
public const RESERVED_NCS = 0;
/**
* Variant: the UUID layout specified in RFC 4122
* Variant: the UUID layout specified in RFC 9562 (formerly RFC 4122)
*
* @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
* @see Uuid::RFC_9562
*/
public const RFC_4122 = 2;
/**
* Variant: the UUID layout specified in RFC 9562 (formerly RFC 4122)
*
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
*/
public const RFC_9562 = 2;
/**
* Variant: reserved, Microsoft Corporation backward compatibility
*
* @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
*/
public const RESERVED_MICROSOFT = 6;
/**
* Variant: reserved for future definition
*
* @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
*/
public const RESERVED_FUTURE = 7;
@@ -130,14 +134,14 @@ class Uuid implements UuidInterface
/**
* Version 1 (Gregorian time) UUID
*
* @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
*/
public const UUID_TYPE_TIME = 1;
/**
* Version 2 (DCE Security) UUID
*
* @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
*/
public const UUID_TYPE_DCE_SECURITY = 2;
@@ -149,21 +153,21 @@ class Uuid implements UuidInterface
/**
* Version 3 (name-based and hashed with MD5) UUID
*
* @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
*/
public const UUID_TYPE_HASH_MD5 = 3;
/**
* Version 4 (random) UUID
*
* @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
*/
public const UUID_TYPE_RANDOM = 4;
/**
* Version 5 (name-based and hashed with SHA1) UUID
*
* @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
*/
public const UUID_TYPE_HASH_SHA1 = 5;
@@ -173,21 +177,23 @@ class Uuid implements UuidInterface
public const UUID_TYPE_PEABODY = 6;
/**
* Version 6 (reordered time) UUID
* Version 6 (reordered Gregorian time) UUID
*
* @link https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis-00#section-5.6 UUID Version 6
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
*/
public const UUID_TYPE_REORDERED_TIME = 6;
/**
* Version 7 (Unix Epoch time) UUID
*
* @link https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis-00#section-5.7 UUID Version 7
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
*/
public const UUID_TYPE_UNIX_TIME = 7;
/**
* @link https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis-00#section-5.8 UUID Version 8
* Version 8 (custom format) UUID
*
* @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
*/
public const UUID_TYPE_CUSTOM = 8;
@@ -229,9 +235,8 @@ class Uuid implements UuidInterface
private static ?UuidFactoryInterface $factory = null;
/**
* @var bool flag to detect if the UUID factory was replaced internally,
* which disables all optimizations for the default/happy path internal
* scenarios
* @var bool flag to detect if the UUID factory was replaced internally, which disables all optimizations for the
* default/happy path internal scenarios
* @phpstan-ignore property.readOnlyByPhpDocDefaultValue
*/
private static bool $factoryReplaced = false;
@@ -244,9 +249,8 @@ class Uuid implements UuidInterface
/**
* Creates a universally unique identifier (UUID) from an array of fields
*
* Unless you're making advanced use of this library to generate identifiers
* that deviate from RFC 4122, you probably do not want to instantiate a
* UUID directly. Use the static methods, instead:
* Unless you're making advanced use of this library to generate identifiers that deviate from RFC 9562 (formerly
* RFC 4122), you probably do not want to instantiate a UUID directly. Use the static methods, instead:
*
* ```
* use Ramsey\Uuid\Uuid;
@@ -258,18 +262,16 @@ class Uuid implements UuidInterface
* ```
*
* @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID
* @param NumberConverterInterface $numberConverter The number converter to use
* for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding
* UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use
* for converting timestamps extracted from a UUID to unix timestamps
* @param NumberConverterInterface $numberConverter The number converter to use for converting hex values to/from integers
* @param CodecInterface $codec The codec to use when encoding or decoding UUID strings
* @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a
* UUID to unix timestamps
*/
public function __construct(
Rfc4122FieldsInterface $fields,
NumberConverterInterface $numberConverter,
CodecInterface $codec,
TimeConverterInterface $timeConverter
TimeConverterInterface $timeConverter,
) {
$this->fields = $fields;
$this->codec = $codec;
@@ -312,8 +314,7 @@ class Uuid implements UuidInterface
/**
* Re-constructs the object from its serialized form
*
* @param string $data The serialized PHP string to unserialize into
* a UuidInterface instance
* @param string $data The serialized PHP string to unserialize into a UuidInterface instance
*/
public function unserialize(string $data): void
{
@@ -427,8 +428,7 @@ class Uuid implements UuidInterface
/**
* Sets the factory used to create UUIDs
*
* @param UuidFactoryInterface $factory A factory that will be used by this
* class to create UUIDs
* @param UuidFactoryInterface $factory A factory that will be used by this class to create UUIDs
*/
public static function setFactory(UuidFactoryInterface $factory): void
{
@@ -445,8 +445,7 @@ class Uuid implements UuidInterface
*
* @param string $bytes A binary string
*
* @return UuidInterface A UuidInterface instance created from a binary
* string representation
* @return UuidInterface A UuidInterface instance created from a binary string representation
*
* @throws InvalidArgumentException
*/
@@ -465,7 +464,7 @@ class Uuid implements UuidInterface
. '-'
. substr($base16Uuid, 16, 4)
. '-'
. substr($base16Uuid, 20, 12)
. substr($base16Uuid, 20, 12),
);
}
@@ -477,8 +476,7 @@ class Uuid implements UuidInterface
*
* @param string $uuid A hexadecimal string
*
* @return UuidInterface A UuidInterface instance created from a hexadecimal
* string representation
* @return UuidInterface A UuidInterface instance created from a hexadecimal string representation
*
* @throws InvalidArgumentException
*/
@@ -498,14 +496,11 @@ class Uuid implements UuidInterface
* Creates a UUID from a DateTimeInterface instance
*
* @param DateTimeInterface $dateTime The date and 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 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
*
* @return UuidInterface A UuidInterface instance that represents a
* version 1 UUID created from a DateTimeInterface instance
* @return UuidInterface A UuidInterface instance that represents a version 1 UUID created from a DateTimeInterface instance
*/
public static function fromDateTime(
DateTimeInterface $dateTime,
@@ -520,8 +515,7 @@ class Uuid implements UuidInterface
*
* @param Hexadecimal $hex Hexadecimal object representing a hexadecimal number
*
* @return UuidInterface A UuidInterface instance created from the Hexadecimal
* object representing a hexadecimal number
* @return UuidInterface A UuidInterface instance created from the Hexadecimal object representing a hexadecimal number
*
* @throws InvalidArgumentException
*/
@@ -544,8 +538,7 @@ class Uuid implements UuidInterface
*
* @param string $integer String representation of 128-bit integer
*
* @return UuidInterface A UuidInterface instance created from the string
* representation of a 128-bit integer
* @return UuidInterface A UuidInterface instance created from the string representation of a 128-bit integer
*
* @throws InvalidArgumentException
*/
@@ -569,18 +562,14 @@ class Uuid implements UuidInterface
}
/**
* Returns a version 1 (Gregorian time) UUID from a host ID, sequence number,
* and the current time
* Returns a version 1 (Gregorian time) UUID from a host ID, sequence number, and the current time
*
* @param Hexadecimal|int|string|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 Hexadecimal | int | string | 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
*
* @return UuidInterface A UuidInterface instance that represents a
* version 1 UUID
* @return UuidInterface A UuidInterface instance that represents a version 1 UUID
*/
public static function uuid1($node = null, ?int $clockSeq = null): UuidInterface
{
@@ -588,24 +577,18 @@ class Uuid implements UuidInterface
}
/**
* Returns a version 2 (DCE Security) UUID from a local domain, local
* identifier, host ID, clock sequence, and the current time
* Returns a version 2 (DCE Security) UUID from a local domain, local identifier, host ID, clock sequence, and the current time
*
* @param int $localDomain The local domain to use when generating bytes,
* according to DCE Security
* @param IntegerObject|null $localIdentifier The local identifier for the
* given domain; this may be a UID or GID on POSIX systems, if the local
* domain is person or group, or it may be a site-defined identifier
* 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 $localDomain The local domain to use when generating bytes, according to DCE Security
* @param IntegerObject | null $localIdentifier The local identifier for the given domain; this may be a UID or GID
* on POSIX systems, if the local domain is "person" or "group," or it may be a site-defined identifier 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).
*
* @return UuidInterface A UuidInterface instance that represents a
* version 2 UUID
* @return UuidInterface A UuidInterface instance that represents a version 2 UUID
*/
public static function uuid2(
int $localDomain,
@@ -617,14 +600,12 @@ class Uuid implements UuidInterface
}
/**
* Returns a version 3 (name-based) UUID based on the MD5 hash of a
* namespace ID and a name
* Returns a version 3 (name-based) UUID based on the MD5 hash of a namespace ID and a name
*
* @param string|UuidInterface $ns The namespace (must be a valid UUID)
* @param UuidInterface | string $ns The namespace (must be a valid UUID)
* @param string $name The name to use for creating a UUID
*
* @return UuidInterface A UuidInterface instance that represents a
* version 3 UUID
* @return UuidInterface A UuidInterface instance that represents a version 3 UUID
*/
public static function uuid3($ns, string $name): UuidInterface
{
@@ -634,8 +615,7 @@ class Uuid implements UuidInterface
/**
* Returns a version 4 (random) UUID
*
* @return UuidInterface A UuidInterface instance that represents a
* version 4 UUID
* @return UuidInterface A UuidInterface instance that represents a version 4 UUID
*/
public static function uuid4(): UuidInterface
{
@@ -643,14 +623,12 @@ class Uuid implements UuidInterface
}
/**
* Returns a version 5 (name-based) UUID based on the SHA-1 hash of a
* namespace ID and a name
* Returns a version 5 (name-based) UUID based on the SHA-1 hash of a namespace ID and a name
*
* @param string|UuidInterface $ns The namespace (must be a valid UUID)
* @param UuidInterface | string $ns The namespace (must be a valid UUID)
* @param string $name The name to use for creating a UUID
*
* @return UuidInterface A UuidInterface instance that represents a
* version 5 UUID
* @return UuidInterface A UuidInterface instance that represents a version 5 UUID
*/
public static function uuid5($ns, string $name): UuidInterface
{
@@ -658,17 +636,13 @@ class Uuid implements UuidInterface
}
/**
* Returns a version 6 (reordered time) UUID from a host ID, sequence number,
* and the current time
* Returns a version 6 (reordered Gregorian 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 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
*
* @return UuidInterface A UuidInterface instance that represents a
* version 6 UUID
* @return UuidInterface A UuidInterface instance that represents a version 6 UUID
*/
public static function uuid6(
?Hexadecimal $node = null,
@@ -680,12 +654,10 @@ class Uuid implements UuidInterface
/**
* Returns a version 7 (Unix Epoch time) UUID
*
* @param DateTimeInterface|null $dateTime An optional date/time from which
* to create the version 7 UUID. If not provided, the UUID is generated
* using the current date/time.
* @param DateTimeInterface | null $dateTime An optional date/time from which to create the version 7 UUID. If not
* provided, the UUID is generated using the current date/time.
*
* @return UuidInterface A UuidInterface instance that represents a
* version 7 UUID
* @return UuidInterface A UuidInterface instance that represents a version 7 UUID
*/
public static function uuid7(?DateTimeInterface $dateTime = null): UuidInterface
{
@@ -696,26 +668,20 @@ class Uuid implements UuidInterface
return $factory->uuid7($dateTime);
}
throw new UnsupportedOperationException(
'The provided factory does not support the uuid7() method',
);
throw new UnsupportedOperationException('The provided factory does not support the uuid7() method');
}
/**
* Returns a version 8 (custom) UUID
* Returns a version 8 (custom format) UUID
*
* The bytes provided may contain any value according to your application's
* needs. Be aware, however, that other applications may not understand the
* semantics of the value.
* The bytes provided may contain any value according to your application's needs. Be aware, however, that other
* applications may not understand the semantics of the value.
*
* @param string $bytes A 16-byte octet string. This is an open blob
* of data that you may fill with 128 bits of information. Be aware,
* however, bits 48 through 51 will be replaced with the UUID version
* field, and bits 64 and 65 will be replaced with the UUID variant. You
* MUST NOT rely on these bits for your application needs.
* @param string $bytes A 16-byte octet string. This is an open blob of data that you may fill with 128 bits of
* information. Be aware, however, bits 48 through 51 will be replaced with the UUID version field, and bits 64
* 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
* @return UuidInterface A UuidInterface instance that represents a version 8 UUID
*/
public static function uuid8(string $bytes): UuidInterface
{
@@ -726,8 +692,6 @@ class Uuid implements UuidInterface
return $factory->uuid8($bytes);
}
throw new UnsupportedOperationException(
'The provided factory does not support the uuid8() method',
);
throw new UnsupportedOperationException('The provided factory does not support the uuid8() method');
}
}
src/UuidFactory.php
+39 -73
View File
@@ -59,13 +59,12 @@ class UuidFactory implements UuidFactoryInterface
private ValidatorInterface $validator;
/**
* @var bool whether the feature set was provided from outside, or we can
* operate under "default" assumptions
* @var bool whether the feature set was provided from outside, or we can operate under "default" assumptions
*/
private bool $isDefaultFeatureSet;
/**
* @param FeatureSet|null $features A set of available features in the current environment
* @param FeatureSet | null $features A set of available features in the current environment
*/
public function __construct(?FeatureSet $features = null)
{
@@ -117,8 +116,7 @@ class UuidFactory implements UuidFactoryInterface
/**
* Sets the name generator to use for this factory
*
* @param NameGeneratorInterface $nameGenerator A generator to generate
* binary data, based on a namespace and name
* @param NameGeneratorInterface $nameGenerator A generator to generate binary data, based on a namespace and name
*/
public function setNameGenerator(NameGeneratorInterface $nameGenerator): void
{
@@ -154,8 +152,7 @@ class UuidFactory implements UuidFactoryInterface
/**
* Sets the time generator to use for this factory
*
* @param TimeGeneratorInterface $generator A generator to generate binary
* data, based on the time
* @param TimeGeneratorInterface $generator A generator to generate binary data, based on the time
*/
public function setTimeGenerator(TimeGeneratorInterface $generator): void
{
@@ -175,8 +172,8 @@ class UuidFactory implements UuidFactoryInterface
/**
* Sets the DCE Security generator to use for this factory
*
* @param DceSecurityGeneratorInterface $generator A generator to generate
* binary data, based on a local domain and local identifier
* @param DceSecurityGeneratorInterface $generator A generator to generate binary data, based on a local domain and
* local identifier
*/
public function setDceSecurityGenerator(DceSecurityGeneratorInterface $generator): void
{
@@ -196,8 +193,7 @@ class UuidFactory implements UuidFactoryInterface
/**
* Sets the random generator to use for this factory
*
* @param RandomGeneratorInterface $generator A generator to generate binary
* data, based on some random input
* @param RandomGeneratorInterface $generator A generator to generate binary data, based on some random input
*/
public function setRandomGenerator(RandomGeneratorInterface $generator): void
{
@@ -209,8 +205,8 @@ class UuidFactory implements UuidFactoryInterface
/**
* Sets the number converter to use for this factory
*
* @param NumberConverterInterface $converter A converter to use for working
* with large integers (i.e. integers greater than PHP_INT_MAX)
* @param NumberConverterInterface $converter A converter to use for working with large integers (i.e., integers
* greater than PHP_INT_MAX)
*/
public function setNumberConverter(NumberConverterInterface $converter): void
{
@@ -230,8 +226,7 @@ class UuidFactory implements UuidFactoryInterface
/**
* Sets the UUID builder to use for this factory
*
* @param UuidBuilderInterface $builder A builder for constructing instances
* of UuidInterface
* @param UuidBuilderInterface $builder A builder for constructing instances of UuidInterface
*/
public function setUuidBuilder(UuidBuilderInterface $builder): void
{
@@ -248,8 +243,7 @@ class UuidFactory implements UuidFactoryInterface
/**
* Sets the validator to use for this factory
*
* @param ValidatorInterface $validator A validator to use for validating
* whether a string is a valid UUID
* @param ValidatorInterface $validator A validator to use for validating whether a string is a valid UUID
*/
public function setValidator(ValidatorInterface $validator): void
{
@@ -281,21 +275,11 @@ class UuidFactory implements UuidFactoryInterface
public function fromDateTime(
DateTimeInterface $dateTime,
?Hexadecimal $node = null,
?int $clockSeq = null
?int $clockSeq = null,
): UuidInterface {
$timeProvider = new FixedTimeProvider(
new Time($dateTime->format('U'), $dateTime->format('u'))
);
$timeGenerator = new DefaultTimeGenerator(
$this->nodeProvider,
$this->timeConverter,
$timeProvider
);
$nodeHex = $node ? $node->toString() : null;
$bytes = $timeGenerator->generate($nodeHex, $clockSeq);
$timeProvider = new FixedTimeProvider(new Time($dateTime->format('U'), $dateTime->format('u')));
$timeGenerator = new DefaultTimeGenerator($this->nodeProvider, $this->timeConverter, $timeProvider);
$bytes = $timeGenerator->generate($node?->toString(), $clockSeq);
return $this->uuidFromBytesAndVersion($bytes, Uuid::UUID_TYPE_TIME);
}
@@ -319,14 +303,9 @@ class UuidFactory implements UuidFactoryInterface
int $localDomain,
?IntegerObject $localIdentifier = null,
?Hexadecimal $node = null,
?int $clockSeq = null
?int $clockSeq = null,
): UuidInterface {
$bytes = $this->dceSecurityGenerator->generate(
$localDomain,
$localIdentifier,
$node,
$clockSeq
);
$bytes = $this->dceSecurityGenerator->generate($localDomain, $localIdentifier, $node, $clockSeq);
return $this->uuidFromBytesAndVersion($bytes, Uuid::UUID_TYPE_DCE_SECURITY);
}
@@ -356,17 +335,15 @@ class UuidFactory implements UuidFactoryInterface
public function uuid6(?Hexadecimal $node = null, ?int $clockSeq = null): UuidInterface
{
$nodeHex = $node ? $node->toString() : null;
$bytes = $this->timeGenerator->generate($nodeHex, $clockSeq);
$bytes = $this->timeGenerator->generate($node?->toString(), $clockSeq);
// Rearrange the bytes, according to the UUID version 6 specification.
$v6 = $bytes[6] . $bytes[7] . $bytes[4] . $bytes[5]
. $bytes[0] . $bytes[1] . $bytes[2] . $bytes[3];
$v6 = bin2hex($v6);
// Drop the first four bits, while adding an empty four bits for the
// version field. This allows us to reconstruct the correct time from
// the bytes of this UUID.
// Drop the first four bits, while adding an empty four bits for the version field. This allows us to
// reconstruct the correct time from the bytes of this UUID.
$v6Bytes = hex2bin(substr($v6, 1, 12) . '0' . substr($v6, -3));
$v6Bytes .= substr($bytes, 8);
@@ -376,12 +353,10 @@ class UuidFactory implements UuidFactoryInterface
/**
* Returns a version 7 (Unix Epoch time) UUID
*
* @param DateTimeInterface|null $dateTime An optional date/time from which
* to create the version 7 UUID. If not provided, the UUID is generated
* using the current date/time.
* @param DateTimeInterface | null $dateTime An optional date/time from which to create the version 7 UUID. If not
* provided, the UUID is generated using the current date/time.
*
* @return UuidInterface A UuidInterface instance that represents a
* version 7 UUID
* @return UuidInterface A UuidInterface instance that represents a version 7 UUID
*/
public function uuid7(?DateTimeInterface $dateTime = null): UuidInterface
{
@@ -392,20 +367,16 @@ class UuidFactory implements UuidFactoryInterface
}
/**
* Returns a version 8 (Custom) UUID
* Returns a version 8 (custom format) UUID
*
* The bytes provided may contain any value according to your application's
* needs. Be aware, however, that other applications may not understand the
* semantics of the value.
* The bytes provided may contain any value according to your application's needs. Be aware, however, that other
* applications may not understand the semantics of the value.
*
* @param string $bytes A 16-byte octet string. This is an open blob
* of data that you may fill with 128 bits of information. Be aware,
* however, bits 48 through 51 will be replaced with the UUID version
* field, and bits 64 and 65 will be replaced with the UUID variant. You
* MUST NOT rely on these bits for your application needs.
* @param string $bytes A 16-byte octet string. This is an open blob of data that you may fill with 128 bits of
* information. Be aware, however, bits 48 through 51 will be replaced with the UUID version field, and bits 64
* 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
* @return UuidInterface A UuidInterface instance that represents a version 8 UUID
*/
public function uuid8(string $bytes): UuidInterface
{
@@ -415,13 +386,11 @@ class UuidFactory implements UuidFactoryInterface
/**
* Returns a Uuid created from the provided byte string
*
* Uses the configured builder and codec and the provided byte string to
* construct a Uuid object.
* Uses the configured builder and codec and the provided byte string to construct a Uuid object.
*
* @param string $bytes The byte string from which to construct a UUID
*
* @return UuidInterface An instance of UuidInterface, created from the
* provided bytes
* @return UuidInterface An instance of UuidInterface, created from the provided bytes
*/
public function uuid(string $bytes): UuidInterface
{
@@ -431,20 +400,18 @@ class UuidFactory implements UuidFactoryInterface
/**
* Returns a version 3 or 5 namespaced Uuid
*
* @param string|UuidInterface $ns The namespace (must be a valid UUID)
* @param UuidInterface | string $ns The namespace (must be a valid UUID)
* @param string $name The name to hash together with the namespace
* @param int $version The version of UUID to create (3 or 5)
* @param string $hashAlgorithm The hashing algorithm to use when hashing
* together the namespace and name
* @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
* @return UuidInterface An instance of UuidInterface, created by hashing together the provided namespace and name
*/
private function uuidFromNsAndName(
UuidInterface | string $ns,
string $name,
int $version,
string $hashAlgorithm
string $hashAlgorithm,
): UuidInterface {
if (!($ns instanceof UuidInterface)) {
$ns = $this->fromString($ns);
@@ -456,13 +423,12 @@ class UuidFactory implements UuidFactoryInterface
}
/**
* Returns an RFC 4122 variant Uuid, created from the provided bytes and version
* Returns a Uuid created from the provided bytes and version
*
* @param string $bytes The byte string to convert to a UUID
* @param int $version The RFC 4122 version to apply to the UUID
* @param int $version The version to apply to the UUID
*
* @return UuidInterface An instance of UuidInterface, created from the
* byte string and version
* @return UuidInterface An instance of UuidInterface, created from the byte string and version
*/
private function uuidFromBytesAndVersion(string $bytes, int $version): UuidInterface
{
src/UuidFactoryInterface.php
+38 -63
View File
@@ -20,8 +20,7 @@ use Ramsey\Uuid\Type\Integer as IntegerObject;
use Ramsey\Uuid\Validator\ValidatorInterface;
/**
* UuidFactoryInterface defines the common functionality all `UuidFactory` instances
* must implement
* UuidFactoryInterface defines the common functionality all `UuidFactory` instances must implement
*/
interface UuidFactoryInterface
{
@@ -30,8 +29,7 @@ interface UuidFactoryInterface
*
* @param string $bytes A binary string
*
* @return UuidInterface A UuidInterface instance created from a binary
* string representation
* @return UuidInterface A UuidInterface instance created from a binary string representation
*/
public function fromBytes(string $bytes): UuidInterface;
@@ -39,19 +37,16 @@ interface UuidFactoryInterface
* Creates a UUID from a DateTimeInterface instance
*
* @param DateTimeInterface $dateTime The date and 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 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
*
* @return UuidInterface A UuidInterface instance that represents a
* version 1 UUID created from a DateTimeInterface instance
* @return UuidInterface A UuidInterface instance that represents a version 1 UUID created from a DateTimeInterface instance
*/
public function fromDateTime(
DateTimeInterface $dateTime,
?Hexadecimal $node = null,
?int $clockSeq = null
?int $clockSeq = null,
): UuidInterface;
/**
@@ -59,8 +54,7 @@ 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
* @return UuidInterface A UuidInterface instance created from the string representation of a 128-bit integer
*/
public function fromInteger(string $integer): UuidInterface;
@@ -69,8 +63,7 @@ interface UuidFactoryInterface
*
* @param string $uuid A hexadecimal string
*
* @return UuidInterface A UuidInterface instance created from a hexadecimal
* string representation
* @return UuidInterface A UuidInterface instance created from a hexadecimal string representation
*/
public function fromString(string $uuid): UuidInterface;
@@ -80,91 +73,73 @@ interface UuidFactoryInterface
public function getValidator(): ValidatorInterface;
/**
* Returns a version 1 (Gregorian time) UUID from a host ID, sequence number,
* and the current time
* Returns a version 1 (Gregorian time) UUID from a host ID, sequence number, and the current time
*
* @param Hexadecimal|int|string|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 Hexadecimal | int | string | 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
*
* @return UuidInterface A UuidInterface instance that represents a
* version 1 UUID
* @return UuidInterface A UuidInterface instance that represents a version 1 UUID
*/
public function uuid1($node = null, ?int $clockSeq = null): UuidInterface;
/**
* Returns a version 2 (DCE Security) UUID from a local domain, local
* identifier, host ID, clock sequence, and the current time
* Returns a version 2 (DCE Security) UUID from a local domain, local identifier, host ID, clock sequence, and the
* current time
*
* @param int $localDomain The local domain to use when generating bytes,
* according to DCE Security
* @param IntegerObject|null $localIdentifier The local identifier for the
* given domain; this may be a UID or GID on POSIX systems, if the local
* domain is person or group, or it may be a site-defined identifier
* 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 $localDomain The local domain to use when generating bytes, according to DCE Security
* @param IntegerObject | null $localIdentifier The local identifier for the given domain; this may be a UID or GID
* on POSIX systems, if the local domain is a person or group, or it may be a site-defined identifier 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
*
* @return UuidInterface A UuidInterface instance that represents a
* version 2 UUID
* @return UuidInterface A UuidInterface instance that represents a version 2 UUID
*/
public function uuid2(
int $localDomain,
?IntegerObject $localIdentifier = null,
?Hexadecimal $node = null,
?int $clockSeq = null
?int $clockSeq = null,
): UuidInterface;
/**
* Returns a version 3 (name-based) UUID based on the MD5 hash of a
* namespace ID and a name
* Returns a version 3 (name-based) UUID based on the MD5 hash of a namespace ID and a name
*
* @param string|UuidInterface $ns The namespace (must be a valid UUID)
* @param UuidInterface | string $ns The namespace (must be a valid UUID)
* @param string $name The name to use for creating a UUID
*
* @return UuidInterface A UuidInterface instance that represents a
* version 3 UUID
* @return UuidInterface A UuidInterface instance that represents a version 3 UUID
*/
public function uuid3($ns, string $name): UuidInterface;
/**
* Returns a version 4 (random) UUID
*
* @return UuidInterface A UuidInterface instance that represents a
* version 4 UUID
* @return UuidInterface A UuidInterface instance that represents a version 4 UUID
*/
public function uuid4(): UuidInterface;
/**
* Returns a version 5 (name-based) UUID based on the SHA-1 hash of a
* namespace ID and a name
* Returns a version 5 (name-based) UUID based on the SHA-1 hash of a namespace ID and a name
*
* @param string|UuidInterface $ns The namespace (must be a valid UUID)
* @param UuidInterface | string $ns The namespace (must be a valid UUID)
* @param string $name The name to use for creating a UUID
*
* @return UuidInterface A UuidInterface instance that represents a
* version 5 UUID
* @return UuidInterface A UuidInterface instance that represents a version 5 UUID
*/
public function uuid5($ns, string $name): UuidInterface;
/**
* Returns a version 6 (reordered time) UUID from a host ID, sequence number,
* and the current time
* 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 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
*
* @return UuidInterface A UuidInterface instance that represents a
* version 6 UUID
* @return UuidInterface A UuidInterface instance that represents a version 6 UUID
*/
public function uuid6(?Hexadecimal $node = null, ?int $clockSeq = null): UuidInterface;
}
src/UuidInterface.php
+10 -15
View File
@@ -22,8 +22,7 @@ use Serializable;
use Stringable;
/**
* A UUID is a universally unique identifier adhering to an agreed-upon
* representation format and standard for generation
* A UUID is a universally unique identifier adhering to an agreed-upon representation format and standard for generation
*
* @immutable
*/
@@ -34,15 +33,10 @@ interface UuidInterface extends
Stringable
{
/**
* Returns -1, 0, or 1 if the UUID is less than, equal to, or greater than
* the other UUID
* Returns -1, 0, or 1 if the UUID is less than, equal to, or greater than the other UUID
*
* The first of two UUIDs is greater than the second if the most
* significant field in which the UUIDs differ is greater for the first
* UUID.
*
* * Q. What's the value of being able to sort UUIDs?
* * A. Use them as keys in a B-Tree or similar mapping.
* The first of two UUIDs is greater than the second if the most significant field in which the UUIDs differ is
* greater for the first UUID.
*
* @param UuidInterface $other The UUID to compare
*
@@ -53,11 +47,10 @@ interface UuidInterface extends
/**
* Returns true if the UUID is equal to the provided object
*
* The result is true if and only if the argument is not null, is a UUID
* object, has the same variant, and contains the same value, bit for bit,
* as the UUID.
* The result is true if and only if the argument is not null, is a UUID object, has the same variant, and contains
* the same value, bit-for-bit, as the UUID.
*
* @param object|null $other An object to test for equality with this UUID
* @param object | null $other An object to test for equality with this UUID
*
* @return bool True if the other object is equal to this UUID
*/
@@ -89,7 +82,9 @@ interface UuidInterface extends
* Returns the string standard representation of the UUID as a URN
*
* @link http://en.wikipedia.org/wiki/Uniform_Resource_Name Uniform Resource Name
* @link https://tools.ietf.org/html/rfc4122#section-3 RFC 4122, § 3: Namespace Registration Template
* @link https://www.rfc-editor.org/rfc/rfc9562.html#section-4 RFC 9562, 4. UUID Format
* @link https://www.rfc-editor.org/rfc/rfc9562.html#section-7 RFC 9562, 7. IANA Considerations
* @link https://www.rfc-editor.org/rfc/rfc4122.html#section-3 RFC 4122, 3. Namespace Registration Template
*/
public function getUrn(): string;
src/functions.php
+30 -47
View File
@@ -20,15 +20,12 @@ use Ramsey\Uuid\Type\Hexadecimal;
use Ramsey\Uuid\Type\Integer as IntegerObject;
/**
* Returns a version 1 (Gregorian time) UUID from a host ID, sequence number,
* and the current time
* Returns a version 1 (Gregorian time) UUID from a host ID, sequence number, and the current time
*
* @param Hexadecimal|int|string|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 Hexadecimal | int | string | 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
*
* @return non-empty-string Version 1 UUID as a string
*/
@@ -38,20 +35,15 @@ function v1($node = null, ?int $clockSeq = null): string
}
/**
* Returns a version 2 (DCE Security) UUID from a local domain, local
* identifier, host ID, clock sequence, and the current time
* Returns a version 2 (DCE Security) UUID from a local domain, local identifier, host ID, clock sequence, and the current time
*
* @param int $localDomain The local domain to use when generating bytes,
* according to DCE Security
* @param IntegerObject|null $localIdentifier The local identifier for the
* given domain; this may be a UID or GID on POSIX systems, if the local
* domain is person or group, or it may be a site-defined identifier
* 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 $localDomain The local domain to use when generating bytes, according to DCE Security
* @param IntegerObject | null $localIdentifier The local identifier for the given domain; this may be a UID or GID on
* POSIX systems, if the local domain is a person or group, or it may be a site-defined identifier 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
*
* @return non-empty-string Version 2 UUID as a string
*/
@@ -59,16 +51,15 @@ function v2(
int $localDomain,
?IntegerObject $localIdentifier = null,
?Hexadecimal $node = null,
?int $clockSeq = null
?int $clockSeq = null,
): string {
return Uuid::uuid2($localDomain, $localIdentifier, $node, $clockSeq)->toString();
}
/**
* Returns a version 3 (name-based) UUID based on the MD5 hash of a
* namespace ID and a name
* Returns a version 3 (name-based) UUID based on the MD5 hash of a namespace ID and a name
*
* @param string|UuidInterface $ns The namespace (must be a valid UUID)
* @param UuidInterface | string $ns The namespace (must be a valid UUID)
*
* @return non-empty-string Version 3 UUID as a string
*/
@@ -88,10 +79,9 @@ function v4(): string
}
/**
* Returns a version 5 (name-based) UUID based on the SHA-1 hash of a
* namespace ID and a name
* Returns a version 5 (name-based) UUID based on the SHA-1 hash of a namespace ID and a name
*
* @param string|UuidInterface $ns The namespace (must be a valid UUID)
* @param UuidInterface | string $ns The namespace (must be a valid UUID)
*
* @return non-empty-string Version 5 UUID as a string
*/
@@ -101,14 +91,11 @@ function v5($ns, string $name): string
}
/**
* Returns a version 6 (reordered time) UUID from a host ID, sequence number,
* and the current time
* Returns a version 6 (reordered Gregorian 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 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
*
* @return non-empty-string Version 6 UUID as a string
*/
@@ -120,9 +107,8 @@ function v6(?Hexadecimal $node = null, ?int $clockSeq = null): string
/**
* Returns a version 7 (Unix Epoch time) UUID
*
* @param DateTimeInterface|null $dateTime An optional date/time from which
* to create the version 7 UUID. If not provided, the UUID is generated
* using the current date/time.
* @param DateTimeInterface|null $dateTime An optional date/time from which to create the version 7 UUID. If not
* provided, the UUID is generated using the current date/time.
*
* @return non-empty-string Version 7 UUID as a string
*/
@@ -132,17 +118,14 @@ function v7(?DateTimeInterface $dateTime = null): string
}
/**
* Returns a version 8 (custom) UUID
* Returns a version 8 (custom format) UUID
*
* The bytes provided may contain any value according to your application's
* needs. Be aware, however, that other applications may not understand the
* semantics of the value.
* The bytes provided may contain any value according to your application's needs. Be aware, however, that other
* applications may not understand the semantics of the value.
*
* @param string $bytes A 16-byte octet string. This is an open blob
* of data that you may fill with 128 bits of information. Be aware,
* however, bits 48 through 51 will be replaced with the UUID version
* field, and bits 64 and 65 will be replaced with the UUID variant. You
* MUST NOT rely on these bits for your application needs.
* @param string $bytes A 16-byte octet string. This is an open blob of data that you may fill with 128 bits of
* information. Be aware, however, bits 48 through 51 will be replaced with the UUID version field, and bits 64 and
* 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
*/