4.0.0-beta1

Added

• Add ValidatorInterface::getPattern() to return the regular expression
  pattern used by the validator.
• Add v6() helper function for version 6 UUIDs.

Changed

• Set the pattern constants on validators as private. Use the getPattern()
  method instead.
• Change the $node parameter for UuidFactoryInterface::uuid6() to accept
  null or Type\Hexadecimal.
• Accept 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.

Removed

• Remove currentTime() method from Provider\Time\FixedTimeProvider and
  Provider\Time\SystemTimeProvider; it had previously been removed from
  Provider\TimeProviderInterface.

4.0.0-alpha5

Added

• Introduce Builder\BuilderCollection and Provider\Node\NodeProviderCollection.

Changed

• 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.

4.0.0-alpha4

Added

• Add a Type\TypeInterface that each of the ramsey/uuid types implements.
• Support version 6 UUIDs; see http://gh.peabody.io/uuidv6/.

Changed

• Rename 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.
• Mark Guid\Guid and Nonstandard\Uuid classes as final.
• Add uuid6() method to UuidFactoryInterface.

Deprecated

• Uuid::UUID_TYPE_IDENTIFIER is deprecated. Use Uuid::UUID_TYPE_DCE_SECURITY
  instead.
• Uuid::VALID_PATTERN is deprecated. Use Validator\GenericValidator::VALID_PATTERN
  instead.

4.0.0-alpha3

Fixed

• Fix microsecond rounding error on 32-bit systems.

4.0.0-alpha2

Added

• 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 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.

Changed

• Add fromDateTime() method to UuidFactoryInterface.
• Change UuidInterface::getHex() to return a Ramsey\Uuid\Type\Hexadecimal instance.
• Change UuidInterface::getInteger() to return a Ramsey\Uuid\Type\IntegerValue instance.

Fixed

• Round microseconds to six digits when getting DateTime from v1 UUIDs. This
  circumvents a needless exception for an otherwise valid time-based UUID.

3.9.3

Fixed

• 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.

4.0.0-alpha1

Added

• Add Validator\ValidatorInterface and Validator\GenericValidator to allow
  flexibility in validating UUIDs/GUIDs.
  • Add ability to change the default validator used by Uuid through
    FeatureSet::setValidator().
  • Add getValidator() and setValidator() to UuidFactory.
• Add an internal 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.
• 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, and
  RandomNodeProvider may throw this exception if random_bytes() or
  random_int() throw an error or exception.
• Add 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.
• 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
  existing Builder\DefaultUuidBuilder, which is now deprecated.
• Add ability to generate version 2 (DCE Security) UUIDs, including the static
  method Uuid::uuid2(), which returns an Rfc4122\UuidV2 instance.
• Add classes to represent GUIDs and nonstandard (non-RFC 4122 variant) UUIDs:
  • Guid\Guid
  • Nonstandard\Uuid.
• Introduce a Builder\FallbackBuilder, used by FeatureSet to help decide
  whether to return a Uuid or Nonstandard\Uuid when decoding a
  UUID string or bytes.
• Introduce Type\Hexadecimal, Type\IntegerValue, and Type\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 and
  Converter\Time\GenericTimeConverter which will use the calculator provided
  to convert numbers and time to values for UUIDs.
• The \DateTimeInterface instance returned by UuidInterface::getDateTime()
  (and now Rfc4122\UuidV1::getDateTime()) now includes microseconds, as
  specified by the version 1 UUID.

Changed

• Set minimum required PHP version to 7.2.
• Add __toString() method to UuidInterface.
• 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 to UuidInterface.
• Add getValidator() method to UuidFactoryInterface.
• Add uuid2() method to UuidFactoryInterface.
• Add convertTime() method to Converter\TimeConverterInterface.
• Add getTime() method to Provider\TimeProviderInterface.
• Change Uuid::getFields() to return an instance of Fields\FieldsInterface.
  Previously, it returned an array of integer values (on 64-bit systems only).
• Change the first required constructor parameter for Uuid from
  array $fields to Rfc4122\FieldsInterface $fields.
• Introduce Converter\TimeConverterInterface $timeConverter as fourth required
  constructor parameter for Uuid and second required constructor parameter for
  Builder\DefaultUuidBuilder.
• Change 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.
• Change the second required parameter of 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.
• 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 using
  OrderedTimeCodec::encodeBinary() and UnsupportedOperationException when
  using OrderedTimeCodec::decodeBytes().
• Out of the box, 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.
• 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 returns Rfc4122\UuidV1
  • Uuid::uuid3 returns Rfc4122\UuidV3
  • Uuid::uuid4 returns Rfc4122\UuidV4
  • Uuid::uuid5 returns Rfc4122\UuidV5

Deprecated

The following functionality is deprecated and will be removed in ramsey/uuid
5.0.0.

• The following methods from 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()
• The following methods from 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.
• 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() 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.
• 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

Removed

• 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.

3.9.2

Fixed

• 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.

3.9.1

Fixed

• Fix 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.

3.9.0

Added

• 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

Changed

• 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.

Deprecated

These will be removed in ramsey/uuid version 4.0.0:

• MtRandGenerator, OpenSslGenerator, and SodiumRandomGenerator are
  deprecated in favor of using the default RandomBytesGenerator.

Fixed

• Set ext-json as a required dependency in composer.json.
• Use PHP_OS instead of php_uname() when determining the system OS, for
  cases when php_uname() is disabled for security reasons.