All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
- Update RFC 4122 validator to recognize version 6 and 7 UUIDs.
- Promote version 6, reordered time UUIDs from the
Nonstandard
namespace to theRfc4122
namespace. Version 6 UUIDs are defined in New UUID Formats, section 5.1. While still an Internet-Draft version 6 is stable and unlikely to change in any way that breaks compatibility. - Add support for version 7, Unix Epoch time UUIDs, as defined in
New UUID Formats, section 5.2. While still an Internet-Draft,
version 7 is stable and unlikely to change in any way that breaks compatibility.
- Use
Ramsey\Uuid\Uuid::uuid7()
to generate version 7 UUIDs. - Version 7 UUIDs are of type
Ramsey\Uuid\Rfc4122\UuidV7
. - The constant
Ramsey\Uuid\Uuid::UUID_TYPE_UNIX_TIME
exists for version 7 UUIDs.
- Use
- Add
Ramsey\Uuid\Converter\Time\UnixTimeConverter
andRamsey\Uuid\Generator\UnixTimeGenerator
to support version 7 UUID generation. - Add support for max UUIDs through
Ramsey\Uuid\Uuid::MAX
andRamsey\Uuid\Rfc4122\MaxUuid
.
- The lowest version of brick/math allowed is now
^0.8.8
.
The following will be removed in ramsey/uuid 5.0.0:
Ramsey\Uuid\Nonstandard\UuidV6
is deprecated in favor ofRamsey\Uuid\Rfc4122\UuidV6
.Ramsey\Uuid\Uuid::UUID_TYPE_PEABODY
; useRamsey\Uuid\Uuid::UUID_TYPE_REORDERED_TIME
instead.
- For
Ramsey\Uuid\Uuid::isValid()
, Psalm now asserts the UUID is a non-empty-string when it is valid. - Nil UUIDs are properly treated as RFC 4122 variants, and
getVariant()
now returns a2
when called on a nil UUID.
- Allow brick/math 0.10.
- Remove dev dependency to moontoast/math.
- Un-deprecate
UuidInterface::getUrn()
.
The following will be removed in ramsey/uuid 5.0.0:
Ramsey\Uuid\Generator\RandomLibAdapter
- Remove support for PHP 7.2, 7.3, and 7.4. This is not a BC break, since Composer will do the right thing for your environment and select a compatible version of this library.
- Require
ext-ctype
extension. For applications that run in environments where theext-ctype
is not present, please require a polyfill, such as symfony/polyfill-ctype. - Use
iterable<UuidBuilderInterface>
instead ofBuilderCollection
types. - Use
iterable<NodeProviderInterface>
instead ofNodeProviderCollection
types.
The following will be removed in ramsey/uuid 5.0.0:
Ramsey\Uuid\Builder\BuilderCollection
Ramsey\Uuid\Provider\Node\NodeProviderCollection
- Dependency on ramsey/collection
- Support valid UUIDs in uppercase in
LazyUuidFromString
.
- Switch back to
^8.0
in the PHP version requirement.
- Indicate support for PHP 8.1, using
~8.1.0
to prevent installations on 8.2 until the library is ready.
- Fix soft BC break with
Uuid::fromString()
signature. The change fromstring
tonon-empty-string
on the parameter annotation introduced a BC break for those using static analysis tools. This release reverts this change and provides an assertion to guard against empty strings. See ramsey/uuid#383.
- Add
Ramsey\Uuid\Exception\UuidExceptionInterface
for all ramsey/uuid exceptions to implement. See ramsey/uuid#340.
- Fix serialization of UUIDs. See ramsey/uuid#361.
- Switch back to
^8.0
in the PHP version requirement.
- Lock 4.1.x to
~8.0.0
to indicate it does not support PHP 8.1.
- Allow use of brick/math version 0.9
- Improve performance of
Uuid::fromString()
,Uuid::fromBytes()
,UuidInterface#toString()
, andUuidInterface#getBytes()
. See PR #324 for more information.
- Switch back to
^8.0
in the PHP version requirement.
- Lock 4.0.x to
~8.0.0
to indicate it does not support PHP 8.1.
- Fix collection deserialization errors due to upstream
allowed_classes
being set tofalse
. For details, see ramsey/uuid#303 and ramsey/collection#47.
- Add support for version 6 UUIDs, as defined by http:https://gh.peabody.io/uuidv6/,
including the static method
Uuid::uuid6()
, which returns aNonstandard\UuidV6
instance. - Add ability to generate version 2 (DCE Security) UUIDs, including the static
method
Uuid::uuid2()
, which returns anRfc4122\UuidV2
instance. - Add classes to represent each version of RFC 4122 UUID. When generating new
UUIDs or creating UUIDs from existing strings, bytes, or integers, if the UUID
is an RFC 4122 variant, one of these instances will be returned:
Rfc4122\UuidV1
Rfc4122\UuidV2
Rfc4122\UuidV3
Rfc4122\UuidV4
Rfc4122\UuidV5
Rfc4122\NilUuid
- Add classes to represent version 6 UUIDs, GUIDs, and nonstandard
(non-RFC 4122 variant) UUIDs:
Nonstandard\UuidV6
Guid\Guid
Nonstandard\Uuid
- Add
Uuid::fromDateTime()
to create version 1 UUIDs from instances of\DateTimeInterface
. - The
\DateTimeInterface
instance returned byUuidInterface::getDateTime()
(and nowRfc4122\UuidV1::getDateTime()
) now includes microseconds, as specified by the version 1 UUID. - Add
Validator\ValidatorInterface
andValidator\GenericValidator
to allow flexibility in validating UUIDs/GUIDs.- The default validator continues to validate UUID strings using the same relaxed validation pattern found in the 3.x series of ramsey/uuid.
- Introduce
Rfc4122\Validator
that may be used for strict validation of RFC 4122 UUID strings. - Add ability to change the default validator used by
Uuid
throughFeatureSet::setValidator()
. - Add
getValidator()
andsetValidator()
toUuidFactory
.
- Add
Provider\Node\StaticNodeProvider
to assist in setting a custom static node value with the multicast bit set for version 1 UUIDs. - Add the following new exceptions:
Exception\BuilderNotFoundException
- Thrown to indicate that no suitable UUID builder could be found.Exception\DateTimeException
- Thrown to indicate that the PHP DateTime extension encountered an exception/error.Exception\DceSecurityException
- Thrown to indicate an exception occurred while dealing with DCE Security (version 2) UUIDs.Exception\InvalidArgumentException
- Thrown to indicate that the argument received is not valid. This extends the built-in PHP\InvalidArgumentException
, so there should be no BC breaks with ramsey/uuid throwing this exception, if you are catching the PHP exception.Exception\InvalidBytesException
- Thrown to indicate that the bytes being operated on are invalid in some way.Exception\NameException
- Thrown to indicate that an error occurred while attempting to hash a namespace and name.Exception\NodeException
- Throw to indicate that attempting to fetch or create a node ID encountered an error.Exception\RandomSourceException
- Thrown to indicate that the source of random data encountered an error.Exception\TimeSourceException
- Thrown to indicate that the source of time encountered an error.Exception\UnableToBuildUuidException
- Thrown to indicate a builder is unable to build a UUID.
- Introduce a
Builder\FallbackBuilder
, used byFeatureSet
to help decide whether to return aUuid
orNonstandard\Uuid
when decoding a UUID string or bytes. - Add
Rfc4122\UuidInterface
to specifically represent RFC 4122 variant UUIDs. - Add
Rfc4122\UuidBuilder
to build RFC 4122 variant UUIDs. This replaces the existingBuilder\DefaultUuidBuilder
, which is now deprecated. - Introduce
Math\CalculatorInterface
for representing calculators to perform arithmetic operations on integers. - Depend on brick/math for the
Math\BrickMathCalculator
, which is the default calculator used by this library when math cannot be performed in native PHP due to integer size limitations. The calculator is configurable and may be changed, if desired. - Add
Converter\Number\GenericNumberConverter
andConverter\Time\GenericTimeConverter
which will use the calculator provided to convert numbers and time to values for UUIDs. - Introduce
Type\Hexadecimal
,Type\Integer
,Type\Decimal
, andType\Time
for improved type-safety when dealing with arbitrary string values. - Add a
Type\TypeInterface
that each of the ramsey/uuid types implements. - Add
Fields\FieldsInterface
andRfc4122\FieldsInterface
to define field layouts for UUID variants. The implementationsRfc4122\Fields
,Guid\Fields
, andNonstandard\Fields
store the 16-byte, binary string representation of the UUID internally, and these manage conversion of the binary string into the hexadecimal field values. - Introduce
Builder\BuilderCollection
andProvider\Node\NodeProviderCollection
. These are typed collections for providing builders and node providers toBuilder\FallbackBuilder
andProvider\Node\FallbackNodeProvider
, respectively. - Add
Generator\NameGeneratorInterface
to support alternate methods of generating bytes for version 3 and version 5 name-based UUID. By default, ramsey/uuid uses theGenerator\DefaultNameGenerator
, which uses the standard algorithm this library has used since the beginning. You may choose to use the newGenerator\PeclUuidNameGenerator
to make use of the newuuid_generate_md5()
anduuid_generate_sha1()
functions in ext-uuid version 1.1.0.
- Set minimum required PHP version to 7.2.
- This library now works on 32-bit and 64-bit systems, with no degradation in functionality.
- By default, the following static methods will now return specific instance
types. This should not cause any BC breaks if typehints target
UuidInterface
:Uuid::uuid1
returnsRfc4122\UuidV1
Uuid::uuid3
returnsRfc4122\UuidV3
Uuid::uuid4
returnsRfc4122\UuidV4
Uuid::uuid5
returnsRfc4122\UuidV5
- Accept
Type\Hexadecimal
for the$node
parameter forUuidFactoryInterface::uuid1()
. This is in addition to theint|string
types already accepted, so there are no BC breaks.Type\Hexadecimal
is now the recommended type to pass for$node
. - Out of the box,
Uuid::fromString()
,Uuid::fromBytes()
, andUuid::fromInteger()
will now return either anRfc4122\UuidInterface
instance or an instance ofNonstandard\Uuid
, depending on whether the input contains an RFC 4122 variant UUID with a valid version identifier. Both implementUuidInterface
, so BC breaks should not occur if typehints use the interface. - Change
Uuid::getFields()
to return an instance ofFields\FieldsInterface
. Previously, it returned an array of integer values (on 64-bit systems only). Uuid::getDateTime()
now returns an instance of\DateTimeImmutable
instead of\DateTime
.- Make the following changes to
UuidInterface
:getHex()
now returns aType\Hexadecimal
instance.getInteger()
now returns aType\Integer
instance. TheType\Integer
instance holds a string representation of a 128-bit integer. You may then use a math library of your choice (bcmath, gmp, etc.) to operate on the string integer.getDateTime()
now returns\DateTimeInterface
instead of\DateTime
.- Add
__toString()
method. - Add
getFields()
method. It returns an instance ofFields\FieldsInterface
.
- Add the following new methods to
UuidFactoryInterface
:uuid2()
uuid6()
fromDateTime()
fromInteger()
getValidator()
- This library no longer throws generic exceptions. However, this should not
result in BC breaks, since the new exceptions extend from built-in PHP
exceptions that this library previously threw.
Exception\UnsupportedOperationException
is now descended from\LogicException
. Previously, it descended from\RuntimeException
.
- Change required constructor parameters for
Uuid
:- Change the first required constructor parameter for
Uuid
fromarray $fields
toRfc4122\FieldsInterface $fields
. - Add
Converter\TimeConverterInterface $timeConverter
as the fourth required constructor parameter forUuid
.
- Change the first required constructor parameter for
- Change the second required parameter of
Builder\UuidBuilderInterface::build()
fromarray $fields
tostring $bytes
. Rather than accepting an array of hexadecimal strings as UUID fields, thebuild()
method now expects a byte string. - Add
Converter\TimeConverterInterface $timeConverter
as the second required constructor parameter forRfc4122\UuidBuilder
. This also affects the now-deprecatedBuilder\DefaultUuidBuilder
, since this class now inherits fromRfc4122\UuidBuilder
. - Add
convertTime()
method toConverter\TimeConverterInterface
. - Add
getTime()
method toProvider\TimeProviderInterface
. It replaces thecurrentTime()
method. Provider\Node\FallbackNodeProvider
now accepts only aProvider\Node\NodeProviderCollection
as its constructor parameter.Provider\Time\FixedTimeProvider
no longer accepts an array but accepts onlyType\Time
instances.Provider\NodeProviderInterface::getNode()
now returnsType\Hexadecimal
instead ofstring|false|null
.Converter/TimeConverterInterface::calculateTime()
now returnsType\Hexadecimal
instead ofarray
. The value is the full UUID timestamp value (count of 100-nanosecond intervals since the Gregorian calendar epoch) in hexadecimal format.- Change methods in
NumberConverterInterface
to accept and return string values instead ofmixed
; this simplifies the interface and makes it consistent. Generator\DefaultTimeGenerator
no longer adds the variant and version bits to the bytes it returns. These must be applied to the bytes afterwards.- When encoding to bytes or decoding from bytes,
OrderedTimeCodec
now checks whether the UUID is an RFC 4122 variant, version 1 UUID. If not, it will throw an exception—InvalidArgumentException
when usingOrderedTimeCodec::encodeBinary()
andUnsupportedOperationException
when usingOrderedTimeCodec::decodeBytes()
.
The following functionality is deprecated and will be removed in ramsey/uuid 5.0.0.
- The following methods from
UuidInterface
andUuid
are deprecated. Use their counterparts on theRfc4122\FieldsInterface
returned byUuid::getFields()
.getClockSeqHiAndReservedHex()
getClockSeqLowHex()
getClockSequenceHex()
getFieldsHex()
getNodeHex()
getTimeHiAndVersionHex()
getTimeLowHex()
getTimeMidHex()
getTimestampHex()
getVariant()
getVersion()
- The following methods from
Uuid
are deprecated. Use theRfc4122\FieldsInterface
instance returned byUuid::getFields()
to get theType\Hexadecimal
value for these fields. You may use the newMath\CalculatorInterface::toIntegerValue()
method to convert theType\Hexadecimal
instances to instances ofType\Integer
. This library providesMath\BrickMathCalculator
, which may be used for this purpose, or you may use the arbitrary-precision arithemetic library of your choice.getClockSeqHiAndReserved()
getClockSeqLow()
getClockSequence()
getNode()
getTimeHiAndVersion()
getTimeLow()
getTimeMid()
getTimestamp()
getDateTime()
onUuidInterface
andUuid
is deprecated. Use this method only on instances ofRfc4122\UuidV1
orNonstandard\UuidV6
.getUrn()
onUuidInterface
andUuid
is deprecated. It is available onRfc4122\UuidInterface
and classes that implement it.- The following methods are deprecated and have no direct replacements. However,
you may obtain the same information by calling
UuidInterface::getHex()
and splitting the return value in half.UuidInterface::getLeastSignificantBitsHex()
UuidInterface::getMostSignificantBitsHex()
Uuid::getLeastSignificantBitsHex()
Uuid::getMostSignificantBitsHex()
Uuid::getLeastSignificantBits()
Uuid::getMostSignificantBits()
UuidInterface::getNumberConverter()
andUuid::getNumberConverter()
are deprecated. There is no alternative recommendation, so plan accordingly.Builder\DefaultUuidBuilder
is deprecated; transition toRfc4122\UuidBuilder
.Converter\Number\BigNumberConverter
is deprecated; transition toConverter\Number\GenericNumberConverter
.Converter\Time\BigNumberTimeConverter
is deprecated; transition toConverter\Time\GenericTimeConverter
.- The classes for representing and generating degraded UUIDs are deprecated.
These are no longer necessary; this library now behaves the same on 32-bit and
64-bit systems.
Builder\DegradedUuidBuilder
Converter\Number\DegradedNumberConverter
Converter\Time\DegradedTimeConverter
DegradedUuid
- The
Uuid::UUID_TYPE_IDENTIFIER
constant is deprecated. UseUuid::UUID_TYPE_DCE_SECURITY
instead. - The
Uuid::VALID_PATTERN
constant is deprecated. UseValidator\GenericValidator::getPattern()
orRfc4122\Validator::getPattern()
instead.
- Remove the following bytes generators and recommend
Generator\RandomBytesGenerator
as a suitable replacement:Generator\MtRandGenerator
Generator\OpenSslGenerator
Generator\SodiumRandomGenerator
- Remove
Exception\UnsatisfiedDependencyException
. This library no longer throws this exception. - Remove the method
Provider\TimeProviderInterface::currentTime()
. UseProvider\TimeProviderInterface::getTime()
instead.
- Add missing convenience methods for
Rfc4122\UuidV2
. - Add
Provider\Node\StaticNodeProvider
to assist in setting a custom static node value with the multicast bit set for version 1 UUIDs.
Provider\NodeProviderInterface::getNode()
now returnsType\Hexadecimal
instead ofstring|false|null
.
- Add
ValidatorInterface::getPattern()
to return the regular expression pattern used by the validator. - Add
v6()
helper function for version 6 UUIDs.
- Set the pattern constants on validators as
private
. Use thegetPattern()
method instead. - Change the
$node
parameter forUuidFactoryInterface::uuid6()
to acceptnull
orType\Hexadecimal
. - Accept
Type\Hexadecimal
for the$node
parameter forUuidFactoryInterface::uuid1()
. This is in addition to theint|string
types already accepted, so there are no BC breaks.Type\Hexadecimal
is now the recommended type to pass for$node
.
- Remove
currentTime()
method fromProvider\Time\FixedTimeProvider
andProvider\Time\SystemTimeProvider
; it had previously been removed fromProvider\TimeProviderInterface
.
- Introduce
Builder\BuilderCollection
andProvider\Node\NodeProviderCollection
.
Builder\FallbackBuilder
now accepts only aBuilder\BuilderCollection
as its constructor parameter.Provider\Node\FallbackNodeProvider
now accepts only aProvider\Node\NodeProviderCollection
as its constructor parameter.Provider\Time\FixedTimeProvider
no longer accepts an array but accepts onlyType\Time
instances.
- Add a
Type\TypeInterface
that each of the ramsey/uuid types implements. - Support version 6 UUIDs; see http:https://gh.peabody.io/uuidv6/.
- Rename
Type\IntegerValue
toType\Integer
. It was originally namedIntegerValue
because static analysis seesInteger
in docblock annotations and treats it as the nativeint
type.Integer
is not a reserved word in PHP, so it should be namedInteger
for consistency with other types in this library. When using it, a class alias prevents static analysis from complaining. - Mark
Guid\Guid
andNonstandard\Uuid
classes asfinal
. - Add
uuid6()
method toUuidFactoryInterface
.
Uuid::UUID_TYPE_IDENTIFIER
is deprecated. UseUuid::UUID_TYPE_DCE_SECURITY
instead.Uuid::VALID_PATTERN
is deprecated. UseValidator\GenericValidator::VALID_PATTERN
instead.
- Fix microsecond rounding error on 32-bit systems.
- Add
Uuid::fromDateTime()
to create version 1 UUIDs from instances of\DateTimeInterface
. - Add
Generator\NameGeneratorInterface
to support alternate methods of generating bytes for version 3 and version 5 name-based UUID. By default, ramsey/uuid uses theGenerator\DefaultNameGenerator
, which uses the standard algorithm this library has used since the beginning. You may choose to use the newGenerator\PeclUuidNameGenerator
to make use of the newuuid_generate_md5()
anduuid_generate_sha1()
functions in ext-uuid version 1.1.0.
- Add
fromDateTime()
method toUuidFactoryInterface
. - Change
UuidInterface::getHex()
to return aRamsey\Uuid\Type\Hexadecimal
instance. - Change
UuidInterface::getInteger()
to return aRamsey\Uuid\Type\IntegerValue
instance.
- Round microseconds to six digits when getting DateTime from v1 UUIDs. This circumvents a needless exception for an otherwise valid time-based UUID.
- Add
Validator\ValidatorInterface
andValidator\GenericValidator
to allow flexibility in validating UUIDs/GUIDs.- Add ability to change the default validator used by
Uuid
throughFeatureSet::setValidator()
. - Add
getValidator()
andsetValidator()
toUuidFactory
.
- Add ability to change the default validator used by
- Add an internal
InvalidArgumentException
that descends from the built-in PHP\InvalidArgumentException
. All places that used to throw\InvalidArgumentException
now throwRamsey\Uuid\Exception\InvalidArgumentException
. This should not cause any BC breaks, however. - Add an internal
DateTimeException
that descends from the built-in PHP\RuntimeException
.Uuid::getDateTime()
may throw this exception if\DateTimeImmutable
throws an error or exception. - Add
RandomSourceException
that descends from the built-in PHP\RuntimeException
.DefaultTimeGenerator
,RandomBytesGenerator
, andRandomNodeProvider
may throw this exception ifrandom_bytes()
orrandom_int()
throw an error or exception. - Add
Fields\FieldsInterface
andRfc4122\FieldsInterface
to define field layouts for UUID variants. The implementationsRfc4122\Fields
,Guid\Fields
, andNonstandard\Fields
store the 16-byte, binary string representation of the UUID internally, and these manage conversion of the binary string into the hexadecimal field values. - Add
Rfc4122\UuidInterface
to specifically represent RFC 4122 variant UUIDs. - Add classes to represent each version of RFC 4122 UUID. When generating new
UUIDs or creating UUIDs from existing strings, bytes, or integers, if the UUID
is an RFC 4122 variant, one of these instances will be returned:
Rfc4122\UuidV1
Rfc4122\UuidV2
Rfc4122\UuidV3
Rfc4122\UuidV4
Rfc4122\UuidV5
Rfc4122\NilUuid
- Add
Rfc4122\UuidBuilder
to build RFC 4122 variant UUIDs. This replaces the existingBuilder\DefaultUuidBuilder
, which is now deprecated. - Add ability to generate version 2 (DCE Security) UUIDs, including the static
method
Uuid::uuid2()
, which returns anRfc4122\UuidV2
instance. - Add classes to represent GUIDs and nonstandard (non-RFC 4122 variant) UUIDs:
Guid\Guid
Nonstandard\Uuid
.
- Introduce a
Builder\FallbackBuilder
, used byFeatureSet
to help decide whether to return aUuid
orNonstandard\Uuid
when decoding a UUID string or bytes. - Introduce
Type\Hexadecimal
,Type\IntegerValue
, andType\Time
for improved type-safety when dealing with arbitrary string values. - Introduce
Math\CalculatorInterface
for representing calculators to perform arithmetic operations on integers. - Depend on brick/math for the
Math\BrickMathCalculator
, which is the default calculator used by this library when math cannot be performed in native PHP due to integer size limitations. The calculator is configurable and may be changed, if desired. - Add
Converter\Number\GenericNumberConverter
andConverter\Time\GenericTimeConverter
which will use the calculator provided to convert numbers and time to values for UUIDs. - The
\DateTimeInterface
instance returned byUuidInterface::getDateTime()
(and nowRfc4122\UuidV1::getDateTime()
) now includes microseconds, as specified by the version 1 UUID.
- Set minimum required PHP version to 7.2.
- Add
__toString()
method toUuidInterface
. - The
UuidInterface::getDateTime()
method now specifies\DateTimeInterface
as the return value, rather than\DateTime
;Uuid::getDateTime()
now returns an instance of\DateTimeImmutable
instead of\DateTime
. - Add
getFields()
method toUuidInterface
. - Add
getValidator()
method toUuidFactoryInterface
. - Add
uuid2()
method toUuidFactoryInterface
. - Add
convertTime()
method toConverter\TimeConverterInterface
. - Add
getTime()
method toProvider\TimeProviderInterface
. - Change
Uuid::getFields()
to return an instance ofFields\FieldsInterface
. Previously, it returned an array of integer values (on 64-bit systems only). - Change the first required constructor parameter for
Uuid
fromarray $fields
toRfc4122\FieldsInterface $fields
. - Introduce
Converter\TimeConverterInterface $timeConverter
as fourth required constructor parameter forUuid
and second required constructor parameter forBuilder\DefaultUuidBuilder
. - Change
UuidInterface::getInteger()
to always return astring
value instead ofmixed
. This is a string representation of a 128-bit integer. You may then use a math library of your choice (bcmath, gmp, etc.) to operate on the string integer. - Change the second required parameter of
Builder\UuidBuilderInterface::build()
fromarray $fields
tostring $bytes
. Rather than accepting an array of hexadecimal strings as UUID fields, thebuild()
method now expects a byte string. Generator\DefaultTimeGenerator
no longer adds the variant and version bits to the bytes it returns. These must be applied to the bytes afterwards.Converter/TimeConverterInterface::calculateTime()
now returnsType\Hexadecimal
instead ofarray
. The value is the full UUID timestamp value (count of 100-nanosecond intervals since the Gregorian calendar epoch) in hexadecimal format.- Change methods in converter interfaces to accept and return string values
instead of
mixed
; this simplifies the interface and makes it consistent:NumberConverterInterface::fromHex(string $hex): string
NumberConverterInterface::toHex(string $number): string
TimeConverterInterface::calculateTime(string $seconds, string $microseconds): array
UnsupportedOperationException
is now descended from\LogicException
. Previously, it descended from\RuntimeException
.- When encoding to bytes or decoding from bytes,
OrderedTimeCodec
now checks whether the UUID is an RFC 4122 variant, version 1 UUID. If not, it will throw an exception—InvalidArgumentException
when usingOrderedTimeCodec::encodeBinary()
andUnsupportedOperationException
when usingOrderedTimeCodec::decodeBytes()
. - Out of the box,
Uuid::fromString()
,Uuid::fromBytes()
, andUuid::fromInteger()
will now return either anRfc4122\UuidInterface
instance or an instance ofNonstandard\Uuid
, depending on whether the input contains an RFC 4122 variant UUID with a valid version identifier. Both implementUuidInterface
, so BC breaks should not occur if typehints use the interface. - By default, the following static methods will now return the specific instance
types. This should not cause any BC breaks if typehints target
UuidInterface
:Uuid::uuid1
returnsRfc4122\UuidV1
Uuid::uuid3
returnsRfc4122\UuidV3
Uuid::uuid4
returnsRfc4122\UuidV4
Uuid::uuid5
returnsRfc4122\UuidV5
The following functionality is deprecated and will be removed in ramsey/uuid 5.0.0.
- The following methods from
UuidInterface
andUuid
are deprecated. Use their counterparts on theRfc4122\FieldsInterface
returned byUuid::getFields()
.getClockSeqHiAndReservedHex()
getClockSeqLowHex()
getClockSequenceHex()
getFieldsHex()
getNodeHex()
getTimeHiAndVersionHex()
getTimeLowHex()
getTimeMidHex()
getTimestampHex()
getVariant()
getVersion()
- The following methods from
Uuid
are deprecated. Use theRfc4122\FieldsInterface
instance returned byUuid::getFields()
to get theType\Hexadecimal
value for these fields, and then use the arbitrary-precision arithmetic library of your choice to convert them to string integers.getClockSeqHiAndReserved()
getClockSeqLow()
getClockSequence()
getNode()
getTimeHiAndVersion()
getTimeLow()
getTimeMid()
getTimestamp()
getDateTime()
onUuidInterface
andUuid
is deprecated. Use this method only on instances ofRfc4122\UuidV1
.getUrn()
onUuidInterface
andUuid
is deprecated. It is available onRfc4122\UuidInterface
and classes that implement it.- The following methods are deprecated and have no direct replacements. However,
you may obtain the same information by calling
UuidInterface::getHex()
and splitting the return value in half.UuidInterface::getLeastSignificantBitsHex()
UuidInterface::getMostSignificantBitsHex()
Uuid::getLeastSignificantBitsHex()
Uuid::getMostSignificantBitsHex()
Uuid::getLeastSignificantBits()
Uuid::getMostSignificantBits()
UuidInterface::getNumberConverter()
andUuid::getNumberConverter()
are deprecated. There is no alternative recommendation, so plan accordingly.Builder\DefaultUuidBuilder
is deprecated; transition toRfc4122\UuidBuilder
.Converter\Number\BigNumberConverter
is deprecated; transition toConverter\Number\GenericNumberConverter
.Converter\Time\BigNumberTimeConverter
is deprecated; transition toConverter\Time\GenericTimeConverter
.Provider\TimeProviderInterface::currentTime()
is deprecated; transition to thegetTimestamp()
method on the same interface.- The classes for representing and generating degraded UUIDs are deprecated.
These are no longer necessary; this library now behaves the same on 32-bit and
64-bit PHP.
Builder\DegradedUuidBuilder
Converter\Number\DegradedNumberConverter
Converter\Time\DegradedTimeConverter
DegradedUuid
- Remove the following bytes generators and recommend
Generator\RandomBytesGenerator
as a suitable replacement:Generator\MtRandGenerator
Generator\OpenSslGenerator
Generator\SodiumRandomGenerator
- Remove
Exception\UnsatisfiedDependencyException
. This library no longer throws this exception.
- Switch back to
^8.0
in the PHP version requirement.
- Indicate support for PHP 8.1, using
~8.1.0
to prevent installations on 8.2 until the library is ready.
- Allow installation of paragonie/random_compat v9.99.100 (for PHP 8 compatibility).
-
For v1 UUIDs, round down for timestamps so that microseconds do not bump the timestamp to the next second.
As an example, consider the case of timestamp
1
with600000
microseconds (1.600000
). This is the first second after midnight on January 1, 1970, UTC. Previous versions of this library had a bug that would round this to2
, so the rendered time was1970-01-01 00:00:02
. This was incorrect. Despite having600000
microseconds, the time should not round up to the next second. Rather, the time should be1970-01-01 00:00:01.600000
. Since this version of ramsey/uuid does not support microseconds, the microseconds are dropped, and the time is1970-01-01 00:00:01
. No rounding should occur.
- Check whether files returned by
/sys/class/net/*/address
are readable before attempting to read them. This avoids a PHP warning that was being emitted on hosts that do not grant permission to read these files.
- Fix
RandomNodeProvider
behavior on 32-bit systems. TheRandomNodeProvider
was converting a 6-byte string to a decimal number, which is a 48-bit, unsigned integer. This caused problems on 32-bit systems and has now been resolved.
- Add function API as convenience. The functions are available in the
Ramsey\Uuid
namespace.v1(int|string|null $node = null, int|null $clockSeq = null): string
v3(string|UuidInterface $ns, string $name): string
v4(): string
v5(string|UuidInterface $ns, string $name): string
- Use paragonie/random-lib instead of ircmaxell/random-lib. This is a non-breaking change.
- Use a high-strength generator by default, when using
RandomLibAdapter
. This is a non-breaking change.
These will be removed in ramsey/uuid version 4.0.0:
MtRandGenerator
,OpenSslGenerator
, andSodiumRandomGenerator
are deprecated in favor of using the defaultRandomBytesGenerator
.
- Set
ext-json
as a required dependency incomposer.json
. - Use
PHP_OS
instead ofphp_uname()
when determining the system OS, for cases whenphp_uname()
is disabled for security reasons.
- Support discovery of MAC addresses on FreeBSD systems
- Use a polyfill to provide PHP ctype functions when running on systems where the ctype functions are not part of the PHP build
- Disallow a trailing newline character when validating UUIDs
- Annotate thrown exceptions for improved IDE hinting
- Gracefully handle cases where
glob()
returns false when searching/sys/class/net/*/address
files on Linux - Fix off-by-one error in
DefaultTimeGenerator
- Switch to
random_int()
frommt_rand()
for better random numbers
- Check sysfs on Linux to determine the node identifier; this provides a reliable way to identify the node on Docker images, etc.
- Set the multicast bit for random nodes, according to RFC 4122, §4.5
- Use
random_bytes()
when generating random nodes
- Add the following UUID version constants:
Uuid::UUID_TYPE_TIME
Uuid::UUID_TYPE_IDENTIFIER
Uuid::UUID_TYPE_HASH_MD5
Uuid::UUID_TYPE_RANDOM
Uuid::UUID_TYPE_HASH_SHA1
- Optimize UUID string decoding by using
str_pad()
instead ofsprintf()
- Add
InvalidUuidStringException
, which is thrown when attempting to decode an invalid string UUID; this does not introduce any BC issues, since the new exception inherits from the previously usedInvalidArgumentException
- Improve memory usage when generating large quantities of UUIDs (use
str_pad()
anddechex()
instead ofsprintf()
)
- Improve test coverage
- Fix issue where the same UUIDs were not being treated as equal when using mixed cases
- Add
OrderedTimeCodec
to store UUID in an optimized way for InnoDB
- Fix invalid node generation in
RandomNodeProvider
- Avoid multiple unnecessary system calls by caching failed attempt to retrieve system node
- Fix test that violated a PHP CodeSniffer rule, breaking the build
- Add
TimestampFirstCombCodec
andTimestampLastCombCodec
codecs to provide the ability to generate COMB sequential UUIDs with the timestamp encoded as either the first 48 bits or the last 48 bits - Improve logic of
CombGenerator
for COMB sequential UUIDs
- Drop the use of OpenSSL as a fallback and use paragonie/random_compat to
support
RandomBytesGenerator
in versions of PHP earlier than 7.0; this addresses and fixes the collision issue
- Add
SodiumRandomGenerator
to allow use of the PECL libsodium extension as a random bytes generator when creating UUIDs
- Implement the PHP
Serializable
interface to provide the ability to serialize/unserialize UUID objects
- Adopt the Contributor Code of Conduct for this project
The 3.0.0 release represents a significant step for the ramsey/uuid library. While the simple and familiar API used in previous versions remains intact, this release provides greater flexibility to integrators, including the ability to inject your own number generators, UUID codecs, node and time providers, and more.
Please note: The changelog for 3.0.0 includes all notes from the alpha and beta versions leading up to this release.
- Add a number of generators that may be used to override the library defaults
for generating random bytes (version 4) or time-based (version 1) UUIDs
CombGenerator
to allow generation of sequential UUIDsOpenSslGenerator
to generate random bytes on systems whereopenssql_random_pseudo_bytes()
is presentMtRandGenerator
to provide a fallback in the event other random generators are not presentRandomLibAdapter
to allow use of ircmaxell/random-libRandomBytesGenerator
for use with PHP 7; ramsey/uuid will default to use this generator when running on PHP 7- Refactor time-based (version 1) UUIDs into a
TimeGeneratorInterface
to allow for other sources to generate version 1 UUIDs in this library PeclUuidTimeGenerator
andPeclUuidRandomGenerator
for creating version 1 or version 4 UUIDs using the pecl-uuid extension
- Add a
setTimeGenerator
method onUuidFactory
to override the default time generator - Add option to enable
PeclUuidTimeGenerator
viaFeatureSet
- Support GUID generation by configuring a
FeatureSet
to use GUIDs - Allow UUIDs to be serialized as JSON through
JsonSerializable
- Change root namespace from "Rhumsaa" to "Ramsey;" in most cases, simply making this change in your applications is the only upgrade path you will need—everything else should work as expected
- No longer consider
Uuid
class asfinal
; everything is now based around interfaces and factories, allowing you to use this package as a base to implement other kinds of UUIDs with different dependencies - Return an object of type
DegradedUuid
on 32-bit systems to indicate that certain features are not available - Default
RandomLibAdapter
to a medium-strength generator with ircmaxell/random-lib; this is configurable, so other generator strengths may be used
- Remove
PeclUuidFactory
in favor of using pecl-uuid with generators - Remove
timeConverter
andtimeProvider
properties, setters, and getters in bothFeatureSet
andUuidFactory
as those are now exclusively used by the defaultTimeGenerator
- Move UUID Doctrine field type to ramsey/uuid-doctrine
- Move
uuid
console application to ramsey/uuid-console - Remove
Uuid::VERSION
package version constant
- Improve GUID support to ensure that:
- On little endian (LE) architectures, the byte order of the first three fields is LE
- On big endian (BE) architectures, it is the same as a GUID
- String representation is always the same
- Fix exception message for
DegradedNumberConverter::fromHex()
- Improve GUID support to ensure that:
- On little endian (LE) architectures, the byte order of the first three fields is LE
- On big endian (BE) architectures, it is the same as a GUID
- String representation is always the same
- Fix exception message for
DegradedNumberConverter::fromHex()
- Enable use of custom
TimeGenerator
implementations - Add a
setTimeGenerator
method onUuidFactory
to override the default time generator - Add option to enable
PeclUuidTimeGenerator
viaFeatureSet
- Remove
timeConverter
andtimeProvider
properties, setters, and getters in bothFeatureSet
andUuidFactory
as those are now exclusively used by the defaultTimeGenerator
- Refactor time-based (version 1) UUIDs into a
TimeGeneratorInterface
to allow for other sources to generate version 1 UUIDs in this library - Add
PeclUuidTimeGenerator
andPeclUuidRandomGenerator
for creating version 1 or version 4 UUIDs using the pecl-uuid extension - Add
RandomBytesGenerator
for use with PHP 7. ramsey/uuid will default to use this generator when running on PHP 7
- Default
RandomLibAdapter
to a medium-strength generator with ircmaxell/random-lib; this is configurable, so other generator strengths may be used
- Remove
PeclUuidFactory
in favor of using pecl-uuid with generators
- Allow dependency injection through
UuidFactory
and/or extendingFeatureSet
to override any package defaults - Add a number of generators that may be used to override the library defaults:
CombGenerator
to allow generation of sequential UUIDsOpenSslGenerator
to generate random bytes on systems whereopenssql_random_pseudo_bytes()
is presentMtRandGenerator
to provide a fallback in the event other random generators are not presentRandomLibAdapter
to allow use of ircmaxell/random-lib
- Support GUID generation by configuring a
FeatureSet
to use GUIDs - Allow UUIDs to be serialized as JSON through
JsonSerializable
- Change root namespace from "Rhumsaa" to "Ramsey;" in most cases, simply making this change in your applications is the only upgrade path you will need—everything else should work as expected
- No longer consider
Uuid
class asfinal
; everything is now based around interfaces and factories, allowing you to use this package as a base to implement other kinds of UUIDs with different dependencies - Return an object of type
DegradedUuid
on 32-bit systems to indicate that certain features are not available
- Move UUID Doctrine field type to ramsey/uuid-doctrine
- Move
uuid
console application to ramsey/uuid-console - Remove
Uuid::VERSION
package version constant
- Drop the use of OpenSSL as a fallback and use paragonie/random_compat to
support
RandomBytesGenerator
in versions of PHP earlier than 7.0; this addresses and fixes the collision issue
- Add support for symfony/console v3 in the
uuid
CLI application
- Fix exception message in
Uuid::calculateUuidTime()
- Ensure the release tag makes it into the rhumsaa/uuid package
- Use
passthru()
and output buffering ingetIfconfig()
- Cache the system node in a static variable so that we process it only once per runtime
- Add static
fromInteger()
method to create UUIDs from string integer orMoontoast\Math\BigNumber
- Improve Doctrine conversion to Uuid or string for the ramsey/uuid Doctrine field type
- Change loop in
generateBytes()
fromforeach
tofor
- Fix upper range for
mt_rand
used in version 4 UUIDs
- Upgrade to PSR-4 autoloading
- Move moontoast/math and symfony/console to require-dev
- Support symfony/console 2.3 (LTS version)
- Add
Uuid::VALID_PATTERN
constant containing a UUID validation regex pattern
- Fix bug where
uuid
console application could not find the Composer autoloader when installed in another project
- Introduce
uuid
console application for generating and decoding UUIDs from CLI (run./bin/uuid
for details) - Add
Uuid::getInteger()
to retrieve aMoontoast\Math\BigNumber
representation of the 128-bit integer representing the UUID - Add
Uuid::getHex()
to retrieve the hexadecimal representation of the UUID - Use
netstat
on Linux to capture the node for a version 1 UUID - Require moontoast/math as part of the regular package requirements
- Use
openssl_random_pseudo_bytes()
, if available, to generate random bytes
- Return
null
fromUuid::getVersion()
if the UUID isn't an RFC 4122 variant - Support string UUIDs without dashes passed to
Uuid::fromString()
- Support creation of UUIDs from bytes with
Uuid::fromBytes()
- Add
Doctrine\UuidType::requiresSQLCommentHint()
method
- Fix cases where the system node was coming back with uppercase hexadecimal digits; this ensures that case in the node is converted to lowercase
- Fix bug in
Uuid::isValid()
where the NIL UUID was not reported as valid
- Allow checking the validity of a UUID through the
Uuid::isValid()
method
- Support UUID generation on 32-bit platforms
- Mark
Uuid
classfinal
- Require moontoast/math on 64-bit platforms for
Uuid::getLeastSignificantBits()
andUuid::getMostSignificantBits()
; the integers returned by these methods are unsigned 64-bit integers and unsupported even on 64-bit builds of PHP - Move
UnsupportedOperationException
to theException
subnamespace
- Relax Doctrine field type conversion rules for UUIDs
- Remove
final
keyword fromUuid
class
- Support ramsey/uuid UUIDs as a Doctrine Database Abstraction Layer (DBAL) field mapping type
- Support generation of version 1, 3, 4, and 5 UUIDs