NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist, #38 most downloaded on Packagist
A PHP library for generating and working with universally unique identifiers (UUIDs).
Latest stable
4.10.0
Last release 7 days ago
14 Nov 2026
Release timing varies
gaps range from 2 weeks to 13 months
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
14 years old
94 releases · first in 2012
Drag across the ruler to compare, or tap a release to open it.
BinaryUtils::applyVariant() and BinaryUtils::applyVersion() are deprecated. ramsey/uuid no longer uses them.
GenericTimeConverter::convertTime() and PhpTimeConverter::convertTime() now return the seconds rounded down, with microseconds that count forward from them. For example, 1.5 seconds before the epoch is now -2 seconds and 500000 microseconds, where it was -1 seconds and 500000 microseconds. The microseconds are added to the seconds, so -2 seconds plus 0.5 seconds is -1.5 seconds. Time::toString() returns -1.500000 for this time. The getDateTime() methods read the time from any TimeConverterInterface implementation in the same way.Uuid::fromString(), the string codecs, and the validators now accept only the standard forms of a UUID string: 32 hexadecimal digits with hyphens in all four standard positions or with no hyphens, optionally in one pair of braces, optionally after one urn: prefix, one uuid: prefix, or both in that order. Before, they removed these prefixes, braces, and (in the codecs) hyphens from anywhere in the string, so strings such as {{6ba7b8109dad-11d180b400c04fd430c8uuid: were read as UUIDs.Uuid::uuid7() now throws InvalidArgumentException for a date before 1970-01-01 00:00:00 UTC or after 10889-08-02 05:31:50.655 UTC. Before, it returned a UUID with a wrong timestamp.Uuid::fromDateTime(), GenericTimeConverter::calculateTime(), and PhpTimeConverter::calculateTime() now throw InvalidArgumentException for a time before the Gregorian calendar epoch, 1582-10-15 00:00:00 UTC. Before, PhpTimeConverter returned a wrong timestamp.Uuid::fromDateTime(), GenericTimeConverter::calculateTime(), and PhpTimeConverter::calculateTime() now throw InvalidArgumentException for a time after 5236-03-31 21:21:00.684697 UTC, the last time that fits in the 60-bit timestamp of a version 1, 2, or 6 UUID. Before, the timestamp lost its highest bits, so the UUID's date started again from 1582.Uuid::uuid7() now stores the fraction of the millisecond in the 12 bits after the version, using method 3 of RFC 9562 section 6.2. Version 7 UUIDs now sort by creation time to about a microsecond, even when different processes created them. They have 62 random bits, where they had 74, and the UUID for a given date and time has different bits after the timestamp than before. UnixTimeGenerator now asks its random generator for 8 bytes for each new counter and 16 bytes for a seed, where it asked for 16 bytes at first and 10 bytes after that.Uuid::uuid7() now throws TimeSourceException when the system clock is before 1970-01-01 00:00:00 UTC or after 10889-08-02 05:31:50.655 UTC, the first and last times a version 7 UUID can have. Before, it returned a UUID with a wrong timestamp. It throws the same exception when calls for the last of those times have used every timestamp that is left.Uuid::uuid7() now throws RandomSourceException when a custom random generator returns a different number of bytes than UnixTimeGenerator asked it for. Before, PHP raised a warning or the UUID had wrong bits.Uuid::uuid8() now throws InvalidArgumentException unless it receives exactly 16 bytes. Before, shorter input raised a TypeError, and the default factory used the first 16 bytes of longer input. The other factory methods throw the same exception when a custom generator returns the wrong number of bytes.BinaryUtils::applyVariant() and BinaryUtils::applyVersion() are deprecated. ramsey/uuid no longer uses them.Uuid::uuid7() no longer changes the UUIDs that later calls without a date return. Before, after a call with a future date, every later call returned a UUID with that date until the clock passed it.PhpTimeConverter::convertTime() no longer returns wrong microseconds, such as dropping a leading zero, depending on the precision ini setting. It now uses integer math; fixed in #653.getDateTime() no longer throws InvalidArgumentException for version 1 and version 6 UUIDs whose time is just before the Unix epoch, such as 1969-12-31 23:59:59.999999; fixed in #645.getDateTime() no longer returns a time after the Unix epoch for UUIDs whose time is less than one second before it.GenericTimeConverter::convertTime() and PhpTimeConverter::convertTime() no longer return a wrong time for times before the Unix epoch. For times less than one second before the epoch, the minus sign was lost. For earlier times, calculateTime() read the returned seconds and microseconds as a different time, so a timestamp 1.5 seconds before the epoch converted back as 0.5 seconds before it.new FeatureSet(useGuids: true) now generate valid GUIDs. Before, uuid1() always threw UnableToBuildUuidException, other methods threw for some values, and the GUIDs they returned had the wrong version. Because of this fix, uuid3() and uuid5() on such a factory now return different GUIDs than before for the same namespace and name, so GUIDs stored from earlier versions will not match; fixed in #651.FeatureSet::setTimeProvider() and FeatureSet::setNodeProvider() now also apply to version 2 (DCE Security) UUIDs, and FeatureSet::setCalculator() now also rebuilds the builder and codec so they use the new calculator. As a result, FeatureSet::getBuilder() and FeatureSet::getCodec() return new objects after setCalculator() is called; fixed in #652.Hexadecimal, Integer, and the $node parameter of Uuid::uuid1() no longer accept a value that ends with a newline character. Before, Uuid::uuid1() returned a malformed UUID for such a node.BuilderCollection::unserialize() and NodeProviderCollection::unserialize() now throw UnsupportedOperationException for a value that is not a serialized array, instead of raising a TypeError.InvalidUuidStringException when the serialized value is not a UUID string. Before, a changed serialized value produced a UuidInterface object whose toString() method returned that value as it was.UuidV2::getLocalDomainName() now throws DceSecurityException for a version 2 UUID whose local domain is not the person, group, or org domain. Before, it raised a TypeError.BrickMathCalculator::divide() now throws InvalidArgumentException for a divisor of zero. Before, it let the brick/math exception through.toUuidV1() or toUuidV6() on a UUID of another version, such as one returned by Uuid::uuid4(), now throws UnsupportedOperationException. Before, it raised a TypeError, an Error, or an AssertionError, depending on the method and the zend.assertions setting.Decimal now removes the whitespace around a numeric string. Before, it kept the whitespace, isNegative() returned false for a negative number with whitespace before it, and BrickMathCalculator could not read the value.Decimal no longer changes a number too small for a float, such as 1e-400, to 0.Decimal, Hexadecimal, Integer, or Time whose serialized value has the wrong type, such as an array, now throws ValueError, and Time::unserialize() throws UnsupportedOperationException. Before, these raised a TypeError.Full Changelog: 4.9.4...4.10.0
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Add support for brick/math ^0.19 , ^0.20 , and ^1.0 ; fixed in #642 .
^0.19, ^0.20, and ^1.0; fixed in #642.Full Changelog: 4.9.3...4.9.4
Upgrade brick/math to support versions ^0.14 to ^0.17 ; fixed in #638 .
^0.14 to ^0.17; fixed in #638.^0.18.Full Changelog: 4.9.2...4.9.3
Remove explicit (int) cast to avoid float-string cast warnings in PHP 8.5.
(int) cast to avoid float-string cast warnings in PHP 8.5.^0.8.16 from ^0.8.8. ramsey/uuid had been using BigInteger::toBytes() in UnixTimeGenerator (for version 7 UUIDs) since v4.6.0, but it wasn't added to brick/math until v0.8.16.Full Changelog: 4.9.1...4.9.2
Allow brick/math version ^0.14 ; fixed in #617 .
^0.14; fixed in #617.microtime() instead of DateTimeImmutable in Ramsey\Uuid\Generator\UnixTimeGenerator.Full Changelog: 4.9.0...4.9.1
Add new @pure annotations to the following ( #605 ):
@pure annotations to the following (#605):
Ramsey\Uuid\Codec\CodecInterface::encode()Ramsey\Uuid\Codec\CodecInterface::encodeBinary()Ramsey\Uuid\Codec\CodecInterface::decode()Ramsey\Uuid\Codec\CodecInterface::decodeBytes()Ramsey\Uuid\Fields\FieldsInterface::getBytes()Ramsey\Uuid\Math\CalculatorInterface::add()Ramsey\Uuid\Math\CalculatorInterface::subtract()Ramsey\Uuid\Math\CalculatorInterface::multiply()Ramsey\Uuid\Math\CalculatorInterface::divide()Ramsey\Uuid\Math\CalculatorInterface::fromBase()Ramsey\Uuid\Math\CalculatorInterface::toBase()Ramsey\Uuid\Math\CalculatorInterface::toHexadecimal()Ramsey\Uuid\Math\CalculatorInterface::toInteger()Ramsey\Uuid\Nonstandard\UuidRamsey\Uuid\Rfc4122\Fields::isMax()Ramsey\Uuid\Rfc4122\FieldsInterface::getVersion()Ramsey\Uuid\Rfc4122\FieldsInterface::isNil()Ramsey\Uuid\Type\Time::getSeconds()Ramsey\Uuid\Type\Time::getMicroseconds()Ramsey\Uuid\Type\TypeInterface::toString()Ramsey\Uuid\UuidInterface::getBytes()Ramsey\Uuid\UuidInterface::toString()Ramsey\Uuid\Validator\ValidatorInterface::validate()@pure annotations that were removed in 4.8.0 (#603).Full Changelog: 4.8.1...4.9.0
This tagged release ensures the stable documentation build matches the current stable release.
Full Changelog: 4.8.0...4.8.1
Ramsey\Uuid\Codec\OrderedTimeCodec is deprecated; please migrate to version 6 UUIDs .
The following will be removed in ramsey/uuid 5.0.0:
Ramsey\Uuid\Codec\OrderedTimeCodec is deprecated; please migrate to version 6 UUIDs.Ramsey\Uuid\Codec\TimestampFirstCombCodec is deprecated; please migrate to version 7 UUIDs.Ramsey\Uuid\Codec\TimestampLastCombCodec is deprecated; please use Ramsey\Uuid\Codec\StringCodec instead.Ramsey\Uuid\Generator\CombGenerator is deprecated; please migrate to version 7 UUIDs.^0.13; fixed in #589.str_getcsv() to avoid deprecation notice in PHP 8.4; fixed in #590.Uuid::fromBytes(), Uuid::fromString(), Uuid::fromDateTime(), Uuid::fromHexadecimal(), and Uuid::fromInteger() to note that each can throw InvalidArgumentException, addressing PHPStan errors occurring at call sites; fixed in #552.getVariant() for MaxUuid now correctly returns Uuid::RESERVED_FUTURE, as specified in RFC 9562, section 5.10.getVariant() for NilUuid now correctly returns Uuid::RESERVED_NCS, as specified in RFC 9562, section 5.9.Full Changelog: 4.7.6...4.8.0
Allow brick/math version ^0.12 .
^0.12.Protect against UUIDv7 collisions within the same millisecond, as reported in #518 and fixed in #522 .
Allow brick/math version ^0.11 .
The original 4.7.2 tag accidentally pointed to a commit in the 5.x branch. I have replaced the 4.7.2 tag with a new tag that points to the correct com
Amend Psalm assertion syntax on Uuid::isValid() to prevent incorrect type inference (#486).
Uuid::isValid() to prevent incorrect type
inference (#486).Allow the use of ramsey/collection ^2.0 with ramsey/uuid.
Add Uuid::fromHexadecimal() and UuidFactory::fromHexadecimal(). These methods are not required by the interfaces.
Uuid::fromHexadecimal() and UuidFactory::fromHexadecimal(). These
methods are not required by the interfaces.00:00:00:00:00:00).Add support for version 8, Unix Epoch time UUIDs, as defined in [draft-ietf-uuidrev-rfc4122bis-00, section 5.8][version8]. While still an Internet-Dra
Ramsey\Uuid\Uuid::uuid8() to generate version 8 UUIDs.Ramsey\Uuid\Rfc4122\UuidV8.Ramsey\Uuid\Uuid::UUID_TYPE_CUSTOM exists for version 8 UUIDs.Update RFC 4122 validator to recognize version 6 and 7 UUIDs.
Ramsey\Uuid\Nonstandard\UuidV6 is deprecated in favor of Ramsey\Uuid\Rfc4122\UuidV6.
Nonstandard namespace to
the Rfc4122 namespace. Version 6 UUIDs are defined in
[draft-ietf-uuidrev-rfc4122bis-00, section 5.6][version6]. While still an
Internet-Draft version 6 is stable and unlikely to change in any way that
breaks compatibility.Ramsey\Uuid\Uuid::uuid7() to generate version 7 UUIDs.Ramsey\Uuid\Rfc4122\UuidV7.Ramsey\Uuid\Uuid::UUID_TYPE_UNIX_TIME exists for version
7 UUIDs.Ramsey\Uuid\Converter\Time\UnixTimeConverter and
Ramsey\Uuid\Generator\UnixTimeGenerator to support version 7 UUID generation.Ramsey\Uuid\Uuid::MAX and
Ramsey\Uuid\Rfc4122\MaxUuid.^0.8.8.The following will be removed in ramsey/uuid 5.0.0:
Ramsey\Uuid\Nonstandard\UuidV6 is deprecated in favor of
Ramsey\Uuid\Rfc4122\UuidV6.Ramsey\Uuid\Uuid::UUID_TYPE_PEABODY; use
Ramsey\Uuid\Uuid::UUID_TYPE_REORDERED_TIME instead.Ramsey\Uuid\Uuid::isValid(), Psalm now asserts the UUID is a
non-empty-string when it is valid.getVariant() now
returns a 2 when called on a nil UUID.Un-deprecate UuidInterface::getUrn().
UuidInterface::getUrn().The following will be removed in ramsey/uuid 5.0.0:
The following will be removed in ramsey/uuid 5.0.0:
Ramsey\Uuid\Generator\RandomLibAdapterRemove 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
ext-ctype extension. For applications that run in environments where
the ext-ctype is not present, please require a polyfill, such as
symfony/polyfill-ctype.iterable<UuidBuilderInterface> instead of BuilderCollection types.iterable<NodeProviderInterface> instead of NodeProviderCollection types.The following will be removed in ramsey/uuid 5.0.0:
Ramsey\Uuid\Builder\BuilderCollectionRamsey\Uuid\Provider\Node\NodeProviderCollectionLazyUuidFromString.Switch back to ^8.0 in the PHP version requirement.
^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.
~8.1.0 to prevent installations on 8.2
until the library is ready.Fix *soft* BC break with Uuid::fromString() signature. The change from string to non-empty-string on the parameter annotation introduced a BC break fo
Uuid::fromString() signature. The change from
string to non-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.
Ramsey\Uuid\Exception\UuidExceptionInterface for all ramsey/uuid
exceptions to implement. See ramsey/uuid#340.Switch back to ^8.0 in the PHP version requirement.
^8.0 in the PHP version requirement.Lock 4.1.x to ~8.0.0 to indicate it does not support PHP 8.1.
~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(), and UuidInterface#getBytes(). See PR #324 for more information
Uuid::fromString(), Uuid::fromBytes(),
UuidInterface#toString(), and UuidInterface#getBytes(). See PR
#324 for more information.Switch back to ^8.0 in the PHP version requirement.
^8.0 in the PHP version requirement.Lock 4.0.x to ~8.0.0 to indicate it does not support PHP 8.1.
~8.0.0 to indicate it does not support PHP 8.1.Fix collection deserialization errors due to upstream allowed_classes being set to false. For details, see ramsey/uuid#303 and ramsey/collection#47.
allowed_classes being
set to false. For details, see ramsey/uuid#303
and ramsey/collection#47.Add Rfc4122\UuidBuilder to build RFC 4122 variant UUIDs. This replaces the existing Builder\DefaultUuidBuilder, which is now deprecated.
Uuid::uuid6(), which returns a
Nonstandard\UuidV6 instance.Uuid::uuid2(), which returns an Rfc4122\UuidV2 instance.Rfc4122\UuidV1Rfc4122\UuidV2Rfc4122\UuidV3Rfc4122\UuidV4Rfc4122\UuidV5Rfc4122\NilUuidNonstandard\UuidV6Guid\GuidNonstandard\UuidUuid::fromDateTime() to create version 1 UUIDs from instances of
\DateTimeInterface.\DateTimeInterface instance returned by UuidInterface::getDateTime()
(and now Rfc4122\UuidV1::getDateTime()) now includes microseconds, as
specified by the version 1 UUID.Validator\ValidatorInterface and Validator\GenericValidator to allow
flexibility in validating UUIDs/GUIDs.
Rfc4122\Validator that may be used for strict validation of
RFC 4122 UUID strings.Uuid through
FeatureSet::setValidator().getValidator() and setValidator() to UuidFactory.Provider\Node\StaticNodeProvider to assist in setting a custom static
node value with the multicast bit set for version 1 UUIDs.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 -
Thrown 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.Builder\FallbackBuilder, used by FeatureSet to help decide
whether to return a Uuid or Nonstandard\Uuid when decoding a
UUID string or bytes.Rfc4122\UuidInterface to specifically represent RFC 4122 variant UUIDs.Rfc4122\UuidBuilder to build RFC 4122 variant UUIDs. This replaces the
existing Builder\DefaultUuidBuilder, which is now deprecated.Math\CalculatorInterface for representing calculators to perform
arithmetic operations on integers.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.Converter\Number\GenericNumberConverter and
Converter\Time\GenericTimeConverter which will use the calculator provided
to convert numbers and time to values for UUIDs.Type\Hexadecimal, Type\Integer, Type\Decimal, and Type\Time
for improved type-safety when dealing with arbitrary string values.Type\TypeInterface that each of the ramsey/uuid types implements.Fields\FieldsInterface and Rfc4122\FieldsInterface to define
field layouts for UUID variants. The implementations Rfc4122\Fields,
Guid\Fields, and Nonstandard\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.Builder\BuilderCollection and Provider\Node\NodeProviderCollection.
These are typed collections for providing builders and node providers to
Builder\FallbackBuilder and Provider\Node\FallbackNodeProvider, respectively.Generator\NameGeneratorInterface to support alternate methods of
generating bytes for version 3 and version 5 name-based UUID. By default,
ramsey/uuid uses the Generator\DefaultNameGenerator, which uses the standard
algorithm this library has used since the beginning. You may choose to use the
new Generator\PeclUuidNameGenerator to make use of the new
uuid_generate_md5() and uuid_generate_sha1() functions in
ext-uuid version 1.1.0.UuidInterface:
Uuid::uuid1 returns Rfc4122\UuidV1Uuid::uuid3 returns Rfc4122\UuidV3Uuid::uuid4 returns Rfc4122\UuidV4Uuid::uuid5 returns Rfc4122\UuidV5Type\Hexadecimal for the $node parameter for
UuidFactoryInterface::uuid1(). This is in addition to the int|string types
already accepted, so there are no BC breaks. Type\Hexadecimal is now the
recommended type to pass for $node.Uuid::fromString(), Uuid::fromBytes(), and
Uuid::fromInteger() will now return either an Rfc4122\UuidInterface
instance or an instance of Nonstandard\Uuid, depending on whether the input
contains an RFC 4122 variant UUID with a valid version identifier. Both
implement UuidInterface, so BC breaks should not occur if typehints use the
interface.Uuid::getFields() to return an instance of Fields\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.UuidInterface:
getHex() now returns a Type\Hexadecimal instance.getInteger() now returns a Type\Integer instance. The Type\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.__toString() method.getFields() method. It returns an instance of Fields\FieldsInterface.UuidFactoryInterface:
uuid2()uuid6()fromDateTime()fromInteger()getValidator()Exception\UnsupportedOperationException is now descended from
\LogicException. Previously, it descended from \RuntimeException.Uuid:
Uuid from
array $fields to Rfc4122\FieldsInterface $fields.Converter\TimeConverterInterface $timeConverter as the fourth
required constructor parameter for Uuid.Builder\UuidBuilderInterface::build()
from array $fields to string $bytes. Rather than accepting an array of
hexadecimal strings as UUID fields, the build() method now expects a byte
string.Converter\TimeConverterInterface $timeConverter as the second required
constructor parameter for Rfc4122\UuidBuilder. This also affects the
now-deprecated Builder\DefaultUuidBuilder, since this class now inherits
from Rfc4122\UuidBuilder.convertTime() method to Converter\TimeConverterInterface.getTime() method to Provider\TimeProviderInterface. It replaces the
currentTime() method.Provider\Node\FallbackNodeProvider now accepts only a
Provider\Node\NodeProviderCollection as its constructor parameter.Provider\Time\FixedTimeProvider no longer accepts an array but accepts only
Type\Time instances.Provider\NodeProviderInterface::getNode() now returns Type\Hexadecimal
instead of string|false|null.Converter/TimeConverterInterface::calculateTime() now returns
Type\Hexadecimal instead of array. The value is the full UUID timestamp
value (count of 100-nanosecond intervals since the Gregorian calendar epoch)
in hexadecimal format.NumberConverterInterface to accept and return string values
instead of mixed; 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.OrderedTimeCodec now checks
whether the UUID is an RFC 4122 variant, version 1 UUID. If not, it will throw
an exception—InvalidArgumentException when using
OrderedTimeCodec::encodeBinary() and UnsupportedOperationException when
using OrderedTimeCodec::decodeBytes().The following functionality is deprecated and will be removed in ramsey/uuid 5.0.0.
UuidInterface and Uuid are deprecated. Use their
counterparts on the Rfc4122\FieldsInterface returned by Uuid::getFields().
getClockSeqHiAndReservedHex()getClockSeqLowHex()getClockSequenceHex()getFieldsHex()getNodeHex()getTimeHiAndVersionHex()getTimeLowHex()getTimeMidHex()getTimestampHex()getVariant()getVersion()Uuid are deprecated. Use the Rfc4122\FieldsInterface
instance returned by Uuid::getFields() to get the Type\Hexadecimal value
for these fields. You may use the new Math\CalculatorInterface::toIntegerValue()
method to convert the Type\Hexadecimal instances to instances of
Type\Integer. This library provides Math\BrickMathCalculator, which may be
used for this purpose, or you may use the arbitrary-precision arithmetic
library of your choice.
getClockSeqHiAndReserved()getClockSeqLow()getClockSequence()getNode()getTimeHiAndVersion()getTimeLow()getTimeMid()getTimestamp()getDateTime() on UuidInterface and Uuid is deprecated. Use this method
only on instances of Rfc4122\UuidV1 or Nonstandard\UuidV6.getUrn() on UuidInterface and Uuid is deprecated. It is available on
Rfc4122\UuidInterface and classes that implement it.UuidInterface::getHex() and
splitting the return value in half.
UuidInterface::getLeastSignificantBitsHex()UuidInterface::getMostSignificantBitsHex()Uuid::getLeastSignificantBitsHex()Uuid::getMostSignificantBitsHex()Uuid::getLeastSignificantBits()Uuid::getMostSignificantBits()UuidInterface::getNumberConverter() and Uuid::getNumberConverter() are
deprecated. There is no alternative recommendation, so plan accordingly.Builder\DefaultUuidBuilder is deprecated; transition to Rfc4122\UuidBuilder.Converter\Number\BigNumberConverter is deprecated; transition to
Converter\Number\GenericNumberConverter.Converter\Time\BigNumberTimeConverter is deprecated; transition to
Converter\Time\GenericTimeConverter.Builder\DegradedUuidBuilderConverter\Number\DegradedNumberConverterConverter\Time\DegradedTimeConverterDegradedUuidUuid::UUID_TYPE_IDENTIFIER constant is deprecated. Use
Uuid::UUID_TYPE_DCE_SECURITY instead.Uuid::VALID_PATTERN constant is deprecated. Use
Validator\GenericValidator::getPattern() or Rfc4122\Validator::getPattern()
instead.Generator\RandomBytesGenerator as a suitable replacement:
Generator\MtRandGeneratorGenerator\OpenSslGeneratorGenerator\SodiumRandomGeneratorException\UnsatisfiedDependencyException. This library no longer
throws this exception.Provider\TimeProviderInterface::currentTime(). Use
Provider\TimeProviderInterface::getTime() instead.Nothing published for this version
Add ValidatorInterface::getPattern() to return the regular expression pattern used by the validator.
ValidatorInterface::getPattern() to return the regular expression
pattern used by the validator.v6() helper function for version 6 UUIDs.private. Use the getPattern()
method instead.$node parameter for UuidFactoryInterface::uuid6() to accept
null or Type\Hexadecimal.Type\Hexadecimal for the $node parameter for
UuidFactoryInterface::uuid1(). This is in addition to the int|string types
already accepted, so there are no BC breaks. Type\Hexadecimal is now the
recommended type to pass for $node.currentTime() method from Provider\Time\FixedTimeProvider and
Provider\Time\SystemTimeProvider; it had previously been removed from
Provider\TimeProviderInterface.Introduce Builder\BuilderCollection and Provider\Node\NodeProviderCollection.
Builder\BuilderCollection and Provider\Node\NodeProviderCollection.Builder\FallbackBuilder now accepts only a Builder\BuilderCollection as
its constructor parameter.Provider\Node\FallbackNodeProvider now accepts only a Provider\Node\NodeProviderCollection
as its constructor parameter.Provider\Time\FixedTimeProvider no longer accepts an array but accepts only
Type\Time instances.Uuid::UUID_TYPE_IDENTIFIER is deprecated. Use Uuid::UUID_TYPE_DCE_SECURITY instead.
Type\TypeInterface that each of the ramsey/uuid types implements.Type\IntegerValue to Type\Integer. It was originally named
IntegerValue because static analysis sees Integer in docblock annotations
and treats it as the native int type. Integer is not a reserved word in
PHP, so it should be named Integer for consistency with other types in this
library. When using it, a class alias prevents static analysis from
complaining.Guid\Guid and Nonstandard\Uuid classes as final.uuid6() method to UuidFactoryInterface.Uuid::UUID_TYPE_IDENTIFIER is deprecated. Use Uuid::UUID_TYPE_DCE_SECURITY
instead.Uuid::VALID_PATTERN is deprecated. Use Validator\GenericValidator::VALID_PATTERN
instead.Fix microsecond rounding error on 32-bit systems.
Add Uuid::fromDateTime() to create version 1 UUIDs from instances of \DateTimeInterface.
Uuid::fromDateTime() to create version 1 UUIDs from instances of
\DateTimeInterface.Generator\NameGeneratorInterface to support alternate methods of
generating bytes for version 3 and version 5 name-based UUID. By default,
ramsey/uuid uses the Generator\DefaultNameGenerator, which uses the standard
algorithm this library has used since the beginning. You may choose to use the
new Generator\PeclUuidNameGenerator to make use of the new
uuid_generate_md5() and uuid_generate_sha1() functions in ext-uuid version
1.1.0.fromDateTime() method to UuidFactoryInterface.UuidInterface::getHex() to return a Ramsey\Uuid\Type\Hexadecimal instance.UuidInterface::getInteger() to return a Ramsey\Uuid\Type\IntegerValue instance.Add Rfc4122\UuidBuilder to build RFC 4122 variant UUIDs. This replaces the existing Builder\DefaultUuidBuilder, which is now deprecated.
Validator\ValidatorInterface and Validator\GenericValidator to allow
flexibility in validating UUIDs/GUIDs.
Uuid through
FeatureSet::setValidator().getValidator() and setValidator() to UuidFactory.InvalidArgumentException that descends from the built-in
PHP \InvalidArgumentException. All places that used to throw
\InvalidArgumentException now throw Ramsey\Uuid\Exception\InvalidArgumentException.
This should not cause any BC breaks, however.DateTimeException that descends from the built-in PHP
\RuntimeException. Uuid::getDateTime() may throw this exception if
\DateTimeImmutable throws an error or exception.RandomSourceException that descends from the built-in PHP
\RuntimeException. DefaultTimeGenerator, RandomBytesGenerator, and
RandomNodeProvider may throw this exception if random_bytes() or
random_int() throw an error or exception.Fields\FieldsInterface and Rfc4122\FieldsInterface to define
field layouts for UUID variants. The implementations Rfc4122\Fields,
Guid\Fields, and Nonstandard\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.Rfc4122\UuidInterface to specifically represent RFC 4122 variant UUIDs.Rfc4122\UuidV1Rfc4122\UuidV2Rfc4122\UuidV3Rfc4122\UuidV4Rfc4122\UuidV5Rfc4122\NilUuidRfc4122\UuidBuilder to build RFC 4122 variant UUIDs. This replaces the
existing Builder\DefaultUuidBuilder, which is now deprecated.Uuid::uuid2(), which returns an Rfc4122\UuidV2 instance.Guid\GuidNonstandard\Uuid.Builder\FallbackBuilder, used by FeatureSet to help decide
whether to return a Uuid or Nonstandard\Uuid when decoding a
UUID string or bytes.Type\Hexadecimal, Type\IntegerValue, and Type\Time for
improved type-safety when dealing with arbitrary string values.Math\CalculatorInterface for representing calculators to perform
arithmetic operations on integers.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.Converter\Number\GenericNumberConverter and
Converter\Time\GenericTimeConverter which will use the calculator provided
to convert numbers and time to values for UUIDs.\DateTimeInterface instance returned by UuidInterface::getDateTime()
(and now Rfc4122\UuidV1::getDateTime()) now includes microseconds, as
specified by the version 1 UUID.__toString() method to UuidInterface.UuidInterface::getDateTime() method now specifies \DateTimeInterface
as the return value, rather than \DateTime; Uuid::getDateTime() now
returns an instance of \DateTimeImmutable instead of \DateTime.getFields() method to UuidInterface.getValidator() method to UuidFactoryInterface.uuid2() method to UuidFactoryInterface.convertTime() method to Converter\TimeConverterInterface.getTime() method to Provider\TimeProviderInterface.Uuid::getFields() to return an instance of Fields\FieldsInterface.
Previously, it returned an array of integer values (on 64-bit systems only).Uuid from
array $fields to Rfc4122\FieldsInterface $fields.Converter\TimeConverterInterface $timeConverter as fourth required
constructor parameter for Uuid and second required constructor parameter for
Builder\DefaultUuidBuilder.UuidInterface::getInteger() to always return a string value instead
of mixed. 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.Builder\UuidBuilderInterface::build()
from array $fields to string $bytes. Rather than accepting an array of
hexadecimal strings as UUID fields, the build() 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 returns
Type\Hexadecimal instead of array. The value is the full UUID timestamp
value (count of 100-nanosecond intervals since the Gregorian calendar epoch)
in hexadecimal format.mixed; this simplifies the interface and makes it consistent:
NumberConverterInterface::fromHex(string $hex): stringNumberConverterInterface::toHex(string $number): stringTimeConverterInterface::calculateTime(string $seconds, string $microseconds): arrayUnsupportedOperationException is now descended from \LogicException.
Previously, it descended from \RuntimeException.OrderedTimeCodec now checks
whether the UUID is an RFC 4122 variant, version 1 UUID. If not, it will throw
an exception—InvalidArgumentException when using
OrderedTimeCodec::encodeBinary() and UnsupportedOperationException when
using OrderedTimeCodec::decodeBytes().Uuid::fromString(), Uuid::fromBytes(), and
Uuid::fromInteger() will now return either an Rfc4122\UuidInterface
instance or an instance of Nonstandard\Uuid, depending on whether the input
contains an RFC 4122 variant UUID with a valid version identifier. Both
implement UuidInterface, so BC breaks should not occur if typehints use the
interface.UuidInterface:
Uuid::uuid1 returns Rfc4122\UuidV1Uuid::uuid3 returns Rfc4122\UuidV3Uuid::uuid4 returns Rfc4122\UuidV4Uuid::uuid5 returns Rfc4122\UuidV5The following functionality is deprecated and will be removed in ramsey/uuid 5.0.0.
UuidInterface and Uuid are deprecated. Use their
counterparts on the Rfc4122\FieldsInterface returned by Uuid::getFields().
getClockSeqHiAndReservedHex()getClockSeqLowHex()getClockSequenceHex()getFieldsHex()getNodeHex()getTimeHiAndVersionHex()getTimeLowHex()getTimeMidHex()getTimestampHex()getVariant()getVersion()Uuid are deprecated. Use the Rfc4122\FieldsInterface
instance returned by Uuid::getFields() to get the Type\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() on UuidInterface and Uuid is deprecated. Use this method
only on instances of Rfc4122\UuidV1.getUrn() on UuidInterface and Uuid is deprecated. It is available on
Rfc4122\UuidInterface and classes that implement it.UuidInterface::getHex() and
splitting the return value in half.
UuidInterface::getLeastSignificantBitsHex()UuidInterface::getMostSignificantBitsHex()Uuid::getLeastSignificantBitsHex()Uuid::getMostSignificantBitsHex()Uuid::getLeastSignificantBits()Uuid::getMostSignificantBits()UuidInterface::getNumberConverter() and Uuid::getNumberConverter() are
deprecated. There is no alternative recommendation, so plan accordingly.Builder\DefaultUuidBuilder is deprecated; transition to
Rfc4122\UuidBuilder.Converter\Number\BigNumberConverter is deprecated; transition to
Converter\Number\GenericNumberConverter.Converter\Time\BigNumberTimeConverter is deprecated; transition to
Converter\Time\GenericTimeConverter.Provider\TimeProviderInterface::currentTime() is deprecated; transition to
the getTimestamp() method on the same interface.Builder\DegradedUuidBuilderConverter\Number\DegradedNumberConverterConverter\Time\DegradedTimeConverterDegradedUuidGenerator\RandomBytesGenerator as a suitable replacement:
Generator\MtRandGeneratorGenerator\OpenSslGeneratorGenerator\SodiumRandomGeneratorException\UnsatisfiedDependencyException. This library no longer
throws this exception.Add #[ReturnTypeWillChange] to Uuid::jsonSerialize() method.
#[ReturnTypeWillChange] to Uuid::jsonSerialize() method.Switch back to ^8.0 in the PHP version requirement.
^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.
~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.
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 with 600000 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 to 2, so
the rendered time was 1970-01-01 00:00:02. This was incorrect. Despite
having 600000 microseconds, the time should not round up to the next second.
Rather, the time should be 1970-01-01 00:00:01.600000. Since this version of
ramsey/uuid does not support microseconds, the microseconds are dropped, and
the time is 1970-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
/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. The RandomNodeProvider was converting a 6-byte string to a decimal number, which is a 48-bit, unsig
RandomNodeProvider behavior on 32-bit systems. The RandomNodeProvider
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.Use paragonie/random-lib instead of ircmaxell/random-lib. This is a non-breaking change.
Ramsey\Uuid namespace.
v1(int|string|null $node = null, int|null $clockSeq = null): stringv3(string|UuidInterface $ns, string $name): stringv4(): stringv5(string|UuidInterface $ns, string $name): stringRandomLibAdapter. This
is a non-breaking change.These will be removed in ramsey/uuid version 4.0.0:
MtRandGenerator, OpenSslGenerator, and SodiumRandomGenerator are
deprecated in favor of using the default RandomBytesGenerator.ext-json as a required dependency in composer.json.PHP_OS instead of php_uname() when determining the system OS, for
cases when php_uname() is disabled for security reasons.Support discovery of MAC addresses on FreeBSD systems
Gracefully handle cases where glob() returns false when searching /sys/class/net/*/address files on Linux
glob() returns false when searching
/sys/class/net/*/address files on LinuxDefaultTimeGeneratorrandom_int() from mt_rand() for better random numbersCheck 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
random_bytes() when generating random nodesAdd the following UUID version constants:
Uuid::UUID_TYPE_TIMEUuid::UUID_TYPE_IDENTIFIERUuid::UUID_TYPE_HASH_MD5Uuid::UUID_TYPE_RANDOMUuid::UUID_TYPE_HASH_SHA1Optimize UUID string decoding by using str_pad() instead of sprintf()
str_pad() instead of sprintf()Add InvalidUuidStringException, which is thrown when attempting to decode an invalid string UUID; this does not introduce any BC issues, since the new
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 used InvalidArgumentExceptionstr_pad()
and dechex() instead of sprintf())### Fixed * 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
OrderedTimeCodec to store UUID in an optimized way for InnoDBRandomNodeProviderFix test that violated a PHP CodeSniffer rule, breaking the build
Add TimestampFirstCombCodec and TimestampLastCombCodec codecs to provide the ability to generate [COMB sequential UUIDs] with the timestamp encoded as
TimestampFirstCombCodec and TimestampLastCombCodec codecs to provide
the ability to generate [COMB sequential UUIDs] with the timestamp encoded as
either the first 48 bits or the last 48 bitsCombGenerator for COMB sequential UUIDsOne column per quarter.