Skip to content

Latest commit

 

History

History
512 lines (394 loc) · 19.4 KB

3-to-4.rst

File metadata and controls

512 lines (394 loc) · 19.4 KB
Raw

Version 3 to 4

I've made great efforts to ensure that the upgrade experience for most will be seamless and uneventful. However, no matter the degree to which you use ramsey/uuid (customized or unchanged), there are a number of things to be aware of as you upgrade your code to use version 4.

Tip

These are the changes that are most likely to affect you. For a full list of changes, take a look at the 4.0.0 changelog.

What's New?

There are a lot of new features in ramsey/uuid! Here are a few of them:

  • Support version 6 UUIDs <nonstandard.version6>.
  • Support version 2 (DCE Security) UUIDs <rfc4122.version2>.
  • 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:
    • :phpRfc4122\\UuidV1 <Ramsey\\Uuid\\Rfc4122\\UuidV1>
    • :phpRfc4122\\UuidV2 <Ramsey\\Uuid\\Rfc4122\\UuidV2>
    • :phpRfc4122\\UuidV3 <Ramsey\\Uuid\\Rfc4122\\UuidV3>
    • :phpRfc4122\\UuidV4 <Ramsey\\Uuid\\Rfc4122\\UuidV4>
    • :phpRfc4122\\UuidV5 <Ramsey\\Uuid\\Rfc4122\\UuidV5>
    • :phpRfc4122\\NilUuid <Ramsey\\Uuid\\Rfc4122\\NilUuid>
  • Add classes to represent version 6 UUIDs, GUIDs, and nonstandard (non-RFC 4122 variants) UUIDs:
    • :phpNonstandard\\UuidV6 <Ramsey\\Uuid\\Nonstandard\\UuidV6>
    • :phpNonstandard\\Uuid <Ramsey\\Uuid\\Nonstandard\\Uuid>
    • :phpGuid\\Guid <Ramsey\\Uuid\\Guid\\Guid>
  • Add :phpUuid::fromDateTime() <Ramsey\\Uuid\\Uuid::fromDateTime> to create version 1 UUIDs from instances of DateTimeInterface.

What's Changed?

Attention

ramsey/uuid version 4 requires PHP 7.2 or later.

Quite a bit has changed, but much remains familiar. Unless you've changed the behavior of ramsey/uuid through custom codecs, providers, generators, etc., the standard functionality and API found in version 3 will not differ much.

Here are the highlights:

  • ramsey/uuid now works on 32-bit and 64-bit systems, with no degradation in functionality! All Degraded* classes are deprecated and no longer used; they'll go away in ramsey/uuid version 5.
  • Pay attention to the return types for the static methods <upgrading.3-to-4.static-methods> on the :phpUuid <Ramsey\\Uuid\\Uuid> class. They've changed slightly, but this won't affect you if your type hints use :phpUuidInterface <Ramsey\\Uuid\\UuidInterface>.
  • The return types for three methods <upgrading.3-to-4.return-types> defined on :phpUuidInterface <Ramsey\\Uuid\\UuidInterface> have changed, breaking backwards compatibility. Take note and update your code.
  • There are a number of deprecations. <upgrading.3-to-4.deprecations> These shouldn't affect you now, but please take a look at the recommendations and update your code soon. These will go away in ramsey/uuid version 5.
  • ramsey/uuid now throws custom exceptions for everything <reference.exceptions>. The exception UnsatisfiedDependencyException no longer exists.
  • If you customize ramsey/uuid at all by implementing the interfaces, take a look at the interface <upgrading.3-to-4.interfaces> and constructor <upgrading.3-to-4.constructors> changes and update your code.

Tip

If you maintain a public project that uses ramsey/uuid version 3 and you find that your code does not require any changes to upgrade to version 4, consider using the following version constraint in your project's composer.json file:

composer require ramsey/uuid:"^3 || ^4"

This will allow any downstream users of your project who aren't ready to upgrade to version 4 the ability to continue using your project while deciding on an appropriate upgrade schedule.

If your downstream users do not specify ramsey/uuid as a dependency, and they use functionality specific to version 3, they may need to update their own Composer dependencies to use ramsey/uuid ^3 to avoid using version 4.

Uuid Static Methods

All the static methods on the :phpUuid <Ramsey\\Uuid\\Uuid> class continue to work as they did in version 3, with this slight change: they now return more-specific types, all of which implement the new interface :phpRfc4122\\UuidInterface <Ramsey\\Uuid\\Rfc4122\\UuidInterface>, which implements the familiar interface :phpUuidInterface <Ramsey\\Uuid\\UuidInterface>.

If your type hints are for :phpUuidInterface <Ramsey\\Uuid\\UuidInterface>, then you should not require any changes.

Return types for Uuid static methods
Method 3.x Returned 4.x Returns
:phpUuid::uuid1() <Ramsey\\Uuid\\Uuid::uuid1> :phpUuid <Ramsey\\Uuid\\Uuid> :phpRfc4122\\UuidV1 <Ramsey\\Uuid\\Rfc4122\\UuidV1>
:phpUuid::uuid3() <Ramsey\\Uuid\\Uuid::uuid3> :phpUuid <Ramsey\\Uuid\\Uuid> :phpRfc4122\\UuidV3 <Ramsey\\Uuid\\Rfc4122\\UuidV3>
:phpUuid::uuid4() <Ramsey\\Uuid\\Uuid::uuid4> :phpUuid <Ramsey\\Uuid\\Uuid> :phpRfc4122\\UuidV4 <Ramsey\\Uuid\\Rfc4122\\UuidV4>
:phpUuid::uuid5() <Ramsey\\Uuid\\Uuid::uuid5> :phpUuid <Ramsey\\Uuid\\Uuid> :phpRfc4122\\UuidV5 <Ramsey\\Uuid\\Rfc4122\\UuidV5>

:phpUuid::fromString() <Ramsey\\Uuid\\Uuid::fromString>, :phpUuid::fromBytes() <Ramsey\\Uuid\\Uuid::fromBytes>, and :phpUuid::fromInteger() <Ramsey\\Uuid\\Uuid::fromInteger> all return an appropriate more-specific type, based on the input value. If the input value is a version 1 UUID, for example, the return type will be an :phpRfc4122\\UuidV1 <Ramsey\\Uuid\\Rfc4122\\UuidV1>. If the input looks like a UUID or is a 128-bit number, but it doesn't validate as an RFC 4122 UUID, the return type will be a :phpNonstandard\\Uuid <Ramsey\\Uuid\\Nonstandard\\Uuid>. These return types implement :phpUuidInterface <Ramsey\\Uuid\\UuidInterface>. If using this as a type hint, you shouldn't need to make any changes.

Changed Return Types

The following :phpUuidInterface <Ramsey\\Uuid\\UuidInterface> method return types have changed in version 4 and you will need to update your code, if you use these methods.

Changed UuidInterface method return types
Method 3.x Returned 4.x Returns
:phpUuidInterface::getFields() <Ramsey\\Uuid\\UuidInterface::getFields> array :phpRfc4122\\FieldsInterface <Ramsey\\Uuid\\Rfc4122\\FieldsInterface>
:phpUuidInterface::getHex() <Ramsey\\Uuid\\UuidInterface::getHex> string :phpType\\Hexadecimal <Ramsey\\Uuid\\Type\\Hexadecimal>
:phpUuidInterface::getInteger() <Ramsey\\Uuid\\UuidInterface::getInteger> mixed1 :phpType\\Integer <Ramsey\\Uuid\\Type\\Integer>

In version 3, the following :phpUuid <Ramsey\\Uuid\\Uuid> methods return int, string, or Moontoast\Math\BigNumber, depending on the environment. In version 4, they all return numeric string values for the sake of consistency. These methods are also deprecated <upgrading.3-to-4.deprecations.uuid> and will be removed in version 5.

  • getClockSeqHiAndReserved()
  • getClockSeqLow()
  • getClockSequence()
  • getLeastSignificantBits()
  • getMostSignificantBits()
  • getNode()
  • getTimeHiAndVersion()
  • getTimeLow()
  • getTimeMid()
  • getTimestamp()

Deprecations

UuidInterface

The following :phpUuidInterface <Ramsey\\Uuid\\UuidInterface> methods are deprecated, but upgrading to version 4 should not cause any problems if using these methods. You are encouraged to update your code according to the recommendations, though, since these methods will go away in version 5.

Deprecated UuidInterface methods
Deprecated Method Update To
getDateTime() Use getDateTime() on :phpUuidV1 <Ramsey\\Uuid\\Rfc4122\\UuidV1::getDateTime>, :phpUuidV2 <Ramsey\\Uuid\\Rfc4122\\UuidV2::getDateTime>, or :phpUuidV6 <Ramsey\\Uuid\\Nonstandard\\UuidV6::getDateTime>
getClockSeqHiAndReservedHex() :phpgetFields()->getClockSeqHiAndReserved()->toString() <Ramsey\\Uuid\\Rfc4122\\FieldsInterface::getClockSeqHiAndReserved>
getClockSeqLowHex() :phpgetFields()->getClockSeqLow()->toString() <Ramsey\\Uuid\\Rfc4122\\FieldsInterface::getClockSeqLow>
getClockSequenceHex() :phpgetFields()->getClockSeq()->toString() <Ramsey\\Uuid\\Rfc4122\\FieldsInterface::getClockSeq>
getFieldsHex() :phpgetFields() <Ramsey\\Uuid\\Rfc4122\\UuidInterface::getFields>2
getLeastSignificantBitsHex() substr($uuid->getHex()->toString(), 0, 16)
getMostSignificantBitsHex() substr($uuid->getHex()->toString(), 16)
getNodeHex() :phpgetFields()->getNode()->toString() <Ramsey\\Uuid\\Rfc4122\\FieldsInterface::getNode>
getNumberConverter() This method has no replacement; plan accordingly.
getTimeHiAndVersionHex() :phpgetFields()->getTimeHiAndVersion()->toString() <Ramsey\\Uuid\\Rfc4122\\FieldsInterface::getTimeHiAndVersion>
getTimeLowHex() :phpgetFields()->getTimeLow()->toString() <Ramsey\\Uuid\\Rfc4122\\FieldsInterface::getTimeLow>
getTimeMidHex() :phpgetFields()->getTimeMid()->toString() <Ramsey\\Uuid\\Rfc4122\\FieldsInterface::getTimeMid>
getTimestampHex() :phpgetFields()->getTimestamp()->toString() <Ramsey\\Uuid\\Rfc4122\\FieldsInterface::getTimestamp>
getUrn() :phpRamsey\\Uuid\\Rfc4122\\UuidInterface::getUrn
getVariant() :phpgetFields()->getVariant() <Ramsey\\Uuid\\Rfc4122\\FieldsInterface::getVariant>
getVersion() :phpgetFields()->getVersion() <Ramsey\\Uuid\\Rfc4122\\FieldsInterface::getVersion>

Uuid

:phpUuid <Ramsey\\Uuid\\Uuid> as an instantiable class is deprecated. In ramsey/uuid version 5, its constructor will be private, and the class will be final. For more information, see faq.final

Note

:phpUuid <Ramsey\\Uuid\\Uuid> is being replaced by more-specific concrete classes, such as:

  • :phpRfc4122\\UuidV1 <Ramsey\\Uuid\\Rfc4122\\UuidV1>
  • :phpRfc4122\\UuidV3 <Ramsey\\Uuid\\Rfc4122\\UuidV3>
  • :phpRfc4122\\UuidV4 <Ramsey\\Uuid\\Rfc4122\\UuidV4>
  • :phpRfc4122\\UuidV5 <Ramsey\\Uuid\\Rfc4122\\UuidV5>
  • :phpNonstandard\\Uuid <Ramsey\\Uuid\\Nonstandard\\Uuid>

However, the :phpUuid <Ramsey\\Uuid\\Uuid> class isn't going away. It will still hold common constants and static methods.

  • Uuid::UUID_TYPE_IDENTIFIER is deprecated. Use Uuid::UUID_TYPE_DCE_SECURITY instead.

  • Uuid::VALID_PATTERN is deprecated. Use the following instead:

    use Ramsey\Uuid\Validator\GenericValidator;
use Ramsey\Uuid\Rfc4122\Validator as Rfc4122Validator;

$genericPattern = (new GenericValidator())->getPattern();
$rfc4122Pattern = (new Rfc4122Validator())->getPattern();

The following :phpUuid <Ramsey\\Uuid\\Uuid> methods are deprecated. If using these methods, you shouldn't have any problems on version 4, but you are encouraged to update your code, since they will go away in version 5.

  • getClockSeqHiAndReserved()
  • getClockSeqLow()
  • getClockSequence()
  • getLeastSignificantBits()
  • getMostSignificantBits()
  • getNode()
  • getTimeHiAndVersion()
  • getTimeLow()
  • getTimeMid()
  • getTimestamp()

Hint

There are no direct replacements for these methods. In ramsey/uuid version 3, they returned int or Moontoast\Math\BigNumber values, depending on the environment. To update your code, you should use the recommended alternates listed in Deprecations: UuidInterface <upgrading.3-to-4.deprecations.uuidinterface>, combined with the arbitrary-precision mathematics library of your choice (e.g., brick/math, gmp, bcmath, etc.).

use Brick\Math\BigInteger;

$node = BigInteger::fromBase($uuid->getFields()->getNode()->toString(), 16);

Interface Changes

For those who customize ramsey/uuid by implementing the interfaces provided, there are a few breaking changes to note.

Hint

Most existing methods on interfaces have type hints added to them. If you implement any interfaces, please be aware of this and update your classes.

UuidInterface

Method Description
:php__toString() <Ramsey\\Uuid\\UuidInterface::__toString> New method; returns string
:phpgetDateTime() <Ramsey\\Uuid\\UuidInterface::getDateTime> Deprecated; now returns DateTimeInterface
:phpgetFields() <Ramsey\\Uuid\\UuidInterface::getFields> Used to return array; now returns :phpRfc4122\\FieldsInterface <Ramsey\\Uuid\\Rfc4122\\FieldsInterface>
:phpgetHex() <Ramsey\\Uuid\\UuidInterface::getHex> Used to return string; now returns :phpType\\Hexadecimal <Ramsey\\Uuid\\Type\\Hexadecimal>
:phpgetInteger() <Ramsey\\Uuid\\UuidInterface::getInteger> New method; returns :phpType\\Integer <Ramsey\\Uuid\\Type\\Integer>

UuidFactoryInterface

Method Description
:phpuuid2() <Ramsey\\Uuid\\UuidFactoryInterface::uuid2> New method; returns :phpRfc4122\\UuidV2 <Ramsey\\Uuid\\Rfc4122\\UuidV2>
:phpuuid6() <Ramsey\\Uuid\\UuidFactoryInterface::uuid6> New method; returns :phpNonstandard\\UuidV6 <Ramsey\\Uuid\\Nonstandard\\UuidV6>
:phpfromDateTime() <Ramsey\\Uuid\\UuidFactoryInterface::fromDateTime> New method; returns :phpUuidInterface <Ramsey\\Uuid\\UuidInterface>
:phpfromInteger() <Ramsey\\Uuid\\UuidFactoryInterface::fromInteger> Changed to accept only strings
:phpgetValidator() <Ramsey\\Uuid\\UuidFactoryInterface::getValidator> New method; returns :phpUuidInterface <Ramsey\\Uuid\\Validator\\ValidatorInterface>

Builder\UuidBuilderInterface

Method Description
build() The second parameter used to accept array $fields; now accepts string $bytes

Converter\TimeConverterInterface

Method Description
calculateTime() Used to return string[]; now returns :phpType\\Hexadecimal <Ramsey\\Uuid\\Type\\Hexadecimal>
convertTime() New method; returns :phpType\\Time <Ramsey\\Uuid\\Type\\Time>

Provider\TimeProviderInterface

Method Description
currentTime() Method removed from interface; use getTime() instead
getTime() New method; returns :phpType\\Time <Ramsey\\Uuid\\Type\\Time>

Provider\NodeProviderInterface

Method Description
getNode() Used to return string|false|null; now returns :phpType\\Hexadecimal <Ramsey\\Uuid\\Type\\Hexadecimal>

Constructor Changes

There are a handful of constructor changes that might affect your use of ramsey/uuid, especially if you customize the library.

Uuid

The constructor for :phpRamsey\\Uuid\\Uuid is deprecated. However, there are a few changes to it that might affect your use of this class.

The first constructor parameter used to be array $fields and is now :phpRfc4122\\FieldsInterface $fields <Ramsey\\Uuid\\Rfc4122\\FieldsInterface>.

Converter\TimeConverterInterface $timeConverter is required as a new fourth parameter.

Builder\DefaultUuidBuilder

While Builder\DefaultUuidBuilder is deprecated, it now inherits from Rfc4122\UuidBuilder, which requires Converter\TimeConverterInterface $timeConverter as its second constructor argument.

Provider\Node\FallbackNodeProvider

Provider\Node\FallbackNodeProvider now requires iterable<Ramsey\Uuid\Provider\NodeProviderInterface> as its constructor parameter.

use MyPackage\MyCustomNodeProvider;
use Ramsey\Uuid\Provider\Node\FallbackNodeProvider;
use Ramsey\Uuid\Provider\Node\RandomNodeProvider;
use Ramsey\Uuid\Provider\Node\SystemNodeProvider;

$nodeProviders = [];
$nodeProviders[] = new MyCustomNodeProvider();
$nodeProviders[] = new SystemNodeProvider();
$nodeProviders[] = new RandomNodeProvider();

$provider = new FallbackNodeProvider($nodeProviders);

Provider\Time\FixedTimeProvider

The constructor for Provider\Time\FixedTimeProvider no longer accepts an array. It accepts :phpType\\Time <Ramsey\\Uuid\\Type\\Time> instances.

Footnotes

  1. This mixed return type could have been an int, string, or Moontoast\Math\BigNumber. In version 4, ramsey/uuid cleans this up for the sake of consistency.↩

  2. The :phpgetFields() <Ramsey\\Uuid\\Rfc4122\\UuidInterface::getFields> method returns a :phpType\\Hexadecimal <Ramsey\\Uuid\\Type\\Hexadecimal> instance; you will need to construct an array if you wish to match the return value of the deprecated getFieldsHex() method.↩