From 0cfd01703478afc948e8a969b714aa62dc5d9435 Mon Sep 17 00:00:00 2001 From: Ben Ramsey Date: Mon, 13 Jan 2020 16:42:23 -0600 Subject: [PATCH] Mark more methods on UuidInterface and Uuid for deprecation --- CHANGELOG.md | 15 +++++++++ src/Rfc4122/FieldsInterface.php | 15 +++++++++ src/Uuid.php | 44 ++++++++++++++++-------- src/UuidInterface.php | 59 +++++++++++---------------------- 4 files changed, 79 insertions(+), 54 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7ebce28..f77ae14 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -123,6 +123,8 @@ The following functionality is deprecated and will be removed in ramsey/uuid * `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 @@ -135,6 +137,19 @@ The following functionality is deprecated and will be removed in ramsey/uuid * `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 diff --git a/src/Rfc4122/FieldsInterface.php b/src/Rfc4122/FieldsInterface.php index 24ef120..a303525 100644 --- a/src/Rfc4122/FieldsInterface.php +++ b/src/Rfc4122/FieldsInterface.php @@ -83,7 +83,17 @@ interface FieldsInterface extends BaseFieldsInterface /** * Returns the variant * + * The variant number describes the layout of the UUID. The variant + * number has the following meaning: + * + * - 0 - Reserved for NCS backward compatibility + * - 2 - The RFC 4122 variant + * - 6 - Reserved, Microsoft Corporation backward compatibility + * - 7 - Reserved for future definition + * * For RFC 4122 variant UUIDs, this value should always be the integer `2`. + * + * @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant */ public function getVariant(): int; @@ -98,6 +108,11 @@ interface FieldsInterface extends BaseFieldsInterface * 3. Name-based UUID hashed with MD5 * 4. Randomly generated UUID * 5. Name-based UUID hashed with SHA-1 + * + * This returns `null` if the UUID is not an RFC 4122 variant, since version + * is only meaningful for this variant. + * + * @link http://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version */ public function getVersion(): ?int; diff --git a/src/Uuid.php b/src/Uuid.php index c44c4b1..a61cfac 100644 --- a/src/Uuid.php +++ b/src/Uuid.php @@ -23,6 +23,7 @@ use Ramsey\Uuid\Exception\DateTimeException; use Ramsey\Uuid\Exception\UnsupportedOperationException; use Ramsey\Uuid\Fields\FieldsInterface; use Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface; +use Throwable; /** * Represents a RFC 4122 universally unique identifier (UUID) @@ -245,19 +246,13 @@ class Uuid implements UuidInterface public function compareTo(UuidInterface $other): int { - if ($this->getMostSignificantBitsHex() < $other->getMostSignificantBitsHex()) { + $compare = strcmp($this->getInteger(), $other->getInteger()); + + if ($compare < 0) { return -1; } - if ($this->getMostSignificantBitsHex() > $other->getMostSignificantBitsHex()) { - return 1; - } - - if ($this->getLeastSignificantBitsHex() < $other->getLeastSignificantBitsHex()) { - return -1; - } - - if ($this->getLeastSignificantBitsHex() > $other->getLeastSignificantBitsHex()) { + if ($compare > 0) { return 1; } @@ -354,6 +349,9 @@ class Uuid implements UuidInterface } /** + * @deprecated In ramsey/uuid version 5.0.0, this will be removed. + * It is available at {@see UuidV1::getDateTime()}. + * * @return DateTimeImmutable An immutable instance of DateTimeInterface * * @throws UnsupportedOperationException if UUID is not time-based @@ -361,7 +359,7 @@ class Uuid implements UuidInterface */ public function getDateTime(): DateTimeInterface { - if ($this->getVersion() !== 1) { + if ($this->fields->getVersion() !== 1) { throw new UnsupportedOperationException('Not a time-based UUID'); } @@ -371,7 +369,7 @@ class Uuid implements UuidInterface try { return new DateTimeImmutable("@{$unixTime}"); - } catch (\Throwable $exception) { + } catch (Throwable $exception) { throw new DateTimeException( $exception->getMessage(), (int) $exception->getCode(), @@ -549,7 +547,7 @@ class Uuid implements UuidInterface */ public function getTimestamp(): string { - if ($this->getVersion() !== 1) { + if ($this->fields->getVersion() !== 1) { throw new UnsupportedOperationException('Not a time-based UUID'); } @@ -563,23 +561,41 @@ class Uuid implements UuidInterface */ public function getTimestampHex(): string { - if ($this->getVersion() !== 1) { + if ($this->fields->getVersion() !== 1) { throw new UnsupportedOperationException('Not a time-based UUID'); } return $this->fields->getTimestamp()->toString(); } + /** + * @deprecated This has moved to {@see Rfc4122FieldsInterface::getUrn()} and + * is available on {@see \Ramsey\Uuid\Rfc4122\UuidV1}, + * {@see \Ramsey\Uuid\Rfc4122\UuidV3}, {@see \Ramsey\Uuid\Rfc4122\UuidV4}, + * and {@see \Ramsey\Uuid\Rfc4122\UuidV5}. + */ public function getUrn(): string { return 'urn:uuid:' . $this->toString(); } + /** + * @deprecated Use {@see UuidInterface::getFields()} to get a + * {@see FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getVariant()}. + */ public function getVariant(): ?int { return $this->fields->getVariant(); } + /** + * @deprecated Use {@see UuidInterface::getFields()} to get a + * {@see FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getVersion()}. + */ public function getVersion(): ?int { return $this->fields->getVersion(); diff --git a/src/UuidInterface.php b/src/UuidInterface.php index eb0e1de..246c453 100644 --- a/src/UuidInterface.php +++ b/src/UuidInterface.php @@ -112,29 +112,27 @@ interface UuidInterface extends JsonSerializable, Serializable public function getClockSequenceHex(): string; /** - * Returns a DateTimeInterface object representing the timestamp associated - * with the UUID - * - * The timestamp value is only meaningful in a time-based UUID, which - * has version type 1. - * - * @return DateTimeInterface A PHP DateTimeInterface instance representing - * the timestamp of a version 1 UUID + * @deprecated In ramsey/uuid version 5.0.0, this will be removed from the + * interface. It is available at {@see UuidV1::getDateTime()}. */ public function getDateTime(): DateTimeInterface; /** - * Returns the 128-bit integer value of the UUID as a string + * Returns the integer value of the UUID as a string */ public function getInteger(): string; /** - * Returns the least significant 64 bits of the UUID + * @deprecated This method will be removed in 5.0.0. There is no direct + * alternative, but the same information may be obtained by splitting + * in half the value returned by {@see UuidInterface::getHex()}. */ public function getLeastSignificantBitsHex(): string; /** - * Returns the most significant 64 bits of the UUID + * @deprecated This method will be removed in 5.0.0. There is no direct + * alternative, but the same information may be obtained by splitting + * in half the value returned by {@see UuidInterface::getHex()}. */ public function getMostSignificantBitsHex(): string; @@ -179,43 +177,24 @@ interface UuidInterface extends JsonSerializable, Serializable public function getTimestampHex(): string; /** - * Returns the string representation of the UUID as a URN - * - * @link http://en.wikipedia.org/wiki/Uniform_Resource_Name Uniform Resource Name + * @deprecated In ramsey/uuid version 5.0.0, this will be removed from this + * interface. It has moved to {@see \Ramsey\Uuid\Rfc4122\UuidInterface::getUrn()}. */ public function getUrn(): string; /** - * Returns the variant - * - * The variant number describes the layout of the UUID. The variant - * number has the following meaning: - * - * * 0 - Reserved for NCS backward compatibility - * * 2 - The RFC 4122 variant - * * 6 - Reserved, Microsoft Corporation backward compatibility - * * 7 - Reserved for future definition - * - * @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant + * @deprecated Use {@see UuidInterface::getFields()} to get a + * {@see FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getVariant()}. */ public function getVariant(): ?int; /** - * Returns the version - * - * The version number describes how the UUID was generated and has the - * following meaning: - * - * * 1 - Time-based UUID - * * 2 - DCE security UUID - * * 3 - Name-based UUID hashed with MD5 - * * 4 - Randomly generated UUID - * * 5 - Name-based UUID hashed with SHA-1 - * - * This returns null if the UUID is not an RFC 4122 variant, since version - * is only meaningful for this variant. - * - * @link http://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version + * @deprecated Use {@see UuidInterface::getFields()} to get a + * {@see FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getVersion()}. */ public function getVersion(): ?int;