Skip to content

4.0.0-alpha1

Pre-release
Pre-release
Compare
Choose a tag to compare
@ramsey ramsey released this 22 Jan 06:48
4.0.0-alpha1
This tag was signed with the committer’s verified signature.
ramsey Ben Ramsey
GPG key ID: B02D97989C8C071B
Learn about vigilant mode.
9988854
This commit was signed with the committer’s verified signature.
ramsey Ben Ramsey
GPG key ID: B02D97989C8C071B
Learn about vigilant mode.

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.
Assets 2