From bc6cd7d88872a1688c7818259bddcc2cc5b8b011 Mon Sep 17 00:00:00 2001 From: Ben Ramsey Date: Tue, 9 Aug 2022 09:18:29 -0500 Subject: [PATCH] Deprecate factory methods; improve deprecation docblocks --- psalm-baseline.xml | 63 ++++++++- src/DeprecatedUuidFactoryInterface.php | 180 ++++++++++++++++++++++++ src/DeprecatedUuidInterface.php | 2 + src/DeprecatedUuidMethodsTrait.php | 121 ++++++++-------- src/FeatureSet.php | 2 + src/Provider/Time/FixedTimeProvider.php | 2 +- src/UuidFactory.php | 4 + src/UuidFactoryInterface.php | 140 ++---------------- 8 files changed, 320 insertions(+), 194 deletions(-) create mode 100644 src/DeprecatedUuidFactoryInterface.php diff --git a/psalm-baseline.xml b/psalm-baseline.xml index e2f6c78..8ddfeaf 100644 --- a/psalm-baseline.xml +++ b/psalm-baseline.xml @@ -39,6 +39,9 @@ + + DegradedUuid + Uuid @@ -65,6 +68,9 @@ + + Guid + parent::__construct($fields, $numberConverter, $codec, $timeConverter) @@ -77,11 +83,20 @@ + + new UuidFactory() + + + LazyUuidFromString + unserialize + + Uuid + parent::__construct($fields, $numberConverter, $codec, $timeConverter) @@ -94,6 +109,9 @@ + + UuidV6 + parent::__construct($fields, $numberConverter, $codec, $timeConverter) @@ -116,6 +134,9 @@ + + NilUuid + Uuid @@ -140,26 +161,41 @@ + + UuidV1 + parent::__construct($fields, $numberConverter, $codec, $timeConverter) + + UuidV2 + parent::__construct($fields, $numberConverter, $codec, $timeConverter) + + UuidV3 + parent::__construct($fields, $numberConverter, $codec, $timeConverter) + + UuidV4 + parent::__construct($fields, $numberConverter, $codec, $timeConverter) + + UuidV5 + parent::__construct($fields, $numberConverter, $codec, $timeConverter) @@ -185,7 +221,16 @@ - + + new UuidFactory() + new UuidFactory() + + + Uuid + + + fromDateTime + getValidator self::getFactory() self::getFactory() self::getFactory() @@ -199,7 +244,16 @@ self::getFactory() self::getFactory() self::getFactory() + uuid1 + uuid2 + uuid3 + uuid4 + uuid5 + uuid6 + + DeprecatedUuidMethodsTrait + getFactory getFactory @@ -213,6 +267,13 @@ + + FeatureSet + new FeatureSet() + + + UuidFactory + $this->codec $this->codec diff --git a/src/DeprecatedUuidFactoryInterface.php b/src/DeprecatedUuidFactoryInterface.php new file mode 100644 index 0000000..2ea38f8 --- /dev/null +++ b/src/DeprecatedUuidFactoryInterface.php @@ -0,0 +1,180 @@ + + * @license http://opensource.org/licenses/MIT MIT + */ + +declare(strict_types=1); + +namespace Ramsey\Uuid; + +use DateTimeInterface; +use Ramsey\Uuid\Type\Hexadecimal; +use Ramsey\Uuid\Type\Integer as IntegerObject; +use Ramsey\Uuid\Validator\ValidatorInterface; + +/** + * This interface encapsulates deprecated methods for ramsey/uuid; this + * interface and its methods will be removed in ramsey/uuid 5.0.0. + * + * @deprecated This interface and its methods will be removed in ramsey/uuid 5.0.0. + */ +interface DeprecatedUuidFactoryInterface +{ + /** + * Creates a UUID from a DateTimeInterface instance + * + * @deprecated In ramsey/uuid version 5, UUID factories will no longer have + * dedicated methods for creating datetime-based UUIDs. Use a dedicated + * factory to generate UUIDs from a DateTime instance. + * + * @param DateTimeInterface $dateTime The date and time + * @param Hexadecimal|null $node A 48-bit number representing the hardware + * address + * @param int|null $clockSeq A 14-bit number used to help avoid duplicates + * that could arise when the clock is set backwards in time or if the + * node ID changes + * + * @return UuidInterface A UuidInterface instance that represents a + * version 1 UUID created from a DateTimeInterface instance + */ + public function fromDateTime( + DateTimeInterface $dateTime, + ?Hexadecimal $node = null, + ?int $clockSeq = null + ): UuidInterface; + + /** + * Returns the validator to use for the factory + * + * @deprecated In ramsey/uuid version 5, UUID factories will no longer have + * dedicated methods for getting validators. Use a dedicated validator + * class to validate UUIDs. + * + * @psalm-mutation-free + */ + public function getValidator(): ValidatorInterface; + + /** + * Returns a version 1 (time-based) UUID from a host ID, sequence number, + * and the current time + * + * @deprecated In ramsey/uuid version 5, UUID factories will no longer have + * methods specific to creating subtypes. Instead, version 5 will use + * dedicated factories for each subtype. + * + * @param Hexadecimal|int|string|null $node A 48-bit number representing the + * hardware address; this number may be represented as an integer or a + * hexadecimal string + * @param int|null $clockSeq A 14-bit number used to help avoid duplicates + * that could arise when the clock is set backwards in time or if the + * node ID changes + * + * @return UuidInterface A UuidInterface instance that represents a + * version 1 UUID + */ + public function uuid1($node = null, ?int $clockSeq = null): UuidInterface; + + /** + * Returns a version 2 (DCE Security) UUID from a local domain, local + * identifier, host ID, clock sequence, and the current time + * + * @deprecated In ramsey/uuid version 5, UUID factories will no longer have + * methods specific to creating subtypes. Instead, version 5 will use + * dedicated factories for each subtype. + * + * @param int $localDomain The local domain to use when generating bytes, + * according to DCE Security + * @param IntegerObject|null $localIdentifier The local identifier for the + * given domain; this may be a UID or GID on POSIX systems, if the local + * domain is person or group, or it may be a site-defined identifier + * if the local domain is org + * @param Hexadecimal|null $node A 48-bit number representing the hardware + * address + * @param int|null $clockSeq A 14-bit number used to help avoid duplicates + * that could arise when the clock is set backwards in time or if the + * node ID changes + * + * @return UuidInterface A UuidInterface instance that represents a + * version 2 UUID + */ + public function uuid2( + int $localDomain, + ?IntegerObject $localIdentifier = null, + ?Hexadecimal $node = null, + ?int $clockSeq = null + ): UuidInterface; + + /** + * Returns a version 3 (name-based) UUID based on the MD5 hash of a + * namespace ID and a name + * + * @deprecated In ramsey/uuid version 5, UUID factories will no longer have + * methods specific to creating subtypes. Instead, version 5 will use + * dedicated factories for each subtype. + * + * @param string|UuidInterface $ns The namespace (must be a valid UUID) + * @param string $name The name to use for creating a UUID + * + * @return UuidInterface A UuidInterface instance that represents a + * version 3 UUID + * + * @psalm-pure + */ + public function uuid3($ns, string $name): UuidInterface; + + /** + * Returns a version 4 (random) UUID + * + * @deprecated In ramsey/uuid version 5, UUID factories will no longer have + * methods specific to creating subtypes. Instead, version 5 will use + * dedicated factories for each subtype. + * + * @return UuidInterface A UuidInterface instance that represents a + * version 4 UUID + */ + public function uuid4(): UuidInterface; + + /** + * Returns a version 5 (name-based) UUID based on the SHA-1 hash of a + * namespace ID and a name + * + * @deprecated In ramsey/uuid version 5, UUID factories will no longer have + * methods specific to creating subtypes. Instead, version 5 will use + * dedicated factories for each subtype. + * + * @param string|UuidInterface $ns The namespace (must be a valid UUID) + * @param string $name The name to use for creating a UUID + * + * @return UuidInterface A UuidInterface instance that represents a + * version 5 UUID + * + * @psalm-pure + */ + public function uuid5($ns, string $name): UuidInterface; + + /** + * Returns a version 6 (ordered-time) UUID from a host ID, sequence number, + * and the current time + * + * @deprecated In ramsey/uuid version 5, UUID factories will no longer have + * methods specific to creating subtypes. Instead, version 5 will use + * dedicated factories for each subtype. + * + * @param Hexadecimal|null $node A 48-bit number representing the hardware + * address + * @param int|null $clockSeq A 14-bit number used to help avoid duplicates + * that could arise when the clock is set backwards in time or if the + * node ID changes + * + * @return UuidInterface A UuidInterface instance that represents a + * version 6 UUID + */ + public function uuid6(?Hexadecimal $node = null, ?int $clockSeq = null): UuidInterface; +} diff --git a/src/DeprecatedUuidInterface.php b/src/DeprecatedUuidInterface.php index 519dc44..017d16d 100644 --- a/src/DeprecatedUuidInterface.php +++ b/src/DeprecatedUuidInterface.php @@ -21,6 +21,8 @@ use Ramsey\Uuid\Converter\NumberConverterInterface; * This interface encapsulates deprecated methods for ramsey/uuid; this * interface and its methods will be removed in ramsey/uuid 5.0.0. * + * @deprecated This interface and its methods will be removed in ramsey/uuid 5.0.0. + * * @psalm-immutable */ interface DeprecatedUuidInterface diff --git a/src/DeprecatedUuidMethodsTrait.php b/src/DeprecatedUuidMethodsTrait.php index e6075d4..d3fbb0c 100644 --- a/src/DeprecatedUuidMethodsTrait.php +++ b/src/DeprecatedUuidMethodsTrait.php @@ -17,10 +17,8 @@ namespace Ramsey\Uuid; use DateTimeImmutable; use DateTimeInterface; use Ramsey\Uuid\Converter\NumberConverterInterface; -use Ramsey\Uuid\Converter\TimeConverterInterface; use Ramsey\Uuid\Exception\DateTimeException; use Ramsey\Uuid\Exception\UnsupportedOperationException; -use Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface; use Throwable; use function str_pad; @@ -32,29 +30,17 @@ use const STR_PAD_LEFT; * This trait encapsulates deprecated methods for ramsey/uuid; this trait and * its methods will be removed in ramsey/uuid 5.0.0. * + * @deprecated This trait and its methods will be removed in ramsey/uuid 5.0.0. + * * @psalm-immutable */ trait DeprecatedUuidMethodsTrait { - /** - * @var Rfc4122FieldsInterface - */ - protected $fields; - - /** - * @var NumberConverterInterface - */ - protected $numberConverter; - - /** - * @var TimeConverterInterface - */ - protected $timeConverter; - /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getClockSeqHiAndReserved()} + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeqHiAndReserved()} * and use the arbitrary-precision math library of your choice to * convert it to a string integer. */ @@ -65,8 +51,9 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getClockSeqHiAndReserved()}. + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeqHiAndReserved()}. */ public function getClockSeqHiAndReservedHex(): string { @@ -75,8 +62,9 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getClockSeqLow()} + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeqLow()} * and use the arbitrary-precision math library of your choice to * convert it to a string integer. */ @@ -87,8 +75,9 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getClockSeqLow()}. + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeqLow()}. */ public function getClockSeqLowHex(): string { @@ -97,8 +86,9 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getClockSeq()} + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeq()} * and use the arbitrary-precision math library of your choice to * convert it to a string integer. */ @@ -109,8 +99,9 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getClockSeq()}. + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getClockSeq()}. */ public function getClockSequenceHex(): string { @@ -157,7 +148,7 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. * * @return string[] */ @@ -219,10 +210,11 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getNode()} - * and use the arbitrary-precision math library of your choice to - * convert it to a string integer. + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getNode()} and use the + * arbitrary-precision math library of your choice to convert it to a + * string integer. */ public function getNode(): string { @@ -231,8 +223,9 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getNode()}. + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getNode()}. */ public function getNodeHex(): string { @@ -241,8 +234,9 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getTimeHiAndVersion()} + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeHiAndVersion()} * and use the arbitrary-precision math library of your choice to * convert it to a string integer. */ @@ -253,8 +247,9 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getTimeHiAndVersion()}. + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeHiAndVersion()}. */ public function getTimeHiAndVersionHex(): string { @@ -263,10 +258,11 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getTimeLow()} - * and use the arbitrary-precision math library of your choice to - * convert it to a string integer. + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeLow()} and use the + * arbitrary-precision math library of your choice to convert it to a + * string integer. */ public function getTimeLow(): string { @@ -275,8 +271,9 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getTimeLow()}. + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeLow()}. */ public function getTimeLowHex(): string { @@ -285,10 +282,11 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getTimeMid()} - * and use the arbitrary-precision math library of your choice to - * convert it to a string integer. + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeMid()} and use the + * arbitrary-precision math library of your choice to convert it to a + * string integer. */ public function getTimeMid(): string { @@ -297,8 +295,9 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getTimeMid()}. + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimeMid()}. */ public function getTimeMidHex(): string { @@ -307,10 +306,11 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getTimestamp()} - * and use the arbitrary-precision math library of your choice to - * convert it to a string integer. + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimestamp()} and use + * the arbitrary-precision math library of your choice to convert it to + * a string integer. */ public function getTimestamp(): string { @@ -323,8 +323,9 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface} - * instance, you may call {@see Rfc4122FieldsInterface::getTimestamp()}. + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call + * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getTimestamp()}. */ public function getTimestampHex(): string { @@ -337,7 +338,7 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getVariant()}. */ @@ -348,7 +349,7 @@ trait DeprecatedUuidMethodsTrait /** * @deprecated Use {@see UuidInterface::getFields()} to get a - * {@see FieldsInterface} instance. If it is a + * {@see \Ramsey\Uuid\Fields\FieldsInterface} instance. If it is a * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface} instance, you may call * {@see \Ramsey\Uuid\Rfc4122\FieldsInterface::getVersion()}. */ diff --git a/src/FeatureSet.php b/src/FeatureSet.php index 819f99a..0a71436 100644 --- a/src/FeatureSet.php +++ b/src/FeatureSet.php @@ -58,6 +58,8 @@ use const PHP_INT_SIZE; * * A feature set is used by UuidFactory to determine the available features and * capabilities of the environment. + * + * @deprecated This class will go away in ramsey/uuid version 5. */ class FeatureSet { diff --git a/src/Provider/Time/FixedTimeProvider.php b/src/Provider/Time/FixedTimeProvider.php index b8bfd72..90b1c6a 100644 --- a/src/Provider/Time/FixedTimeProvider.php +++ b/src/Provider/Time/FixedTimeProvider.php @@ -19,7 +19,7 @@ use Ramsey\Uuid\Type\Integer as IntegerObject; use Ramsey\Uuid\Type\Time; /** - * FixedTimeProvider uses an known time to provide the time + * FixedTimeProvider uses a known time to provide the time * * This provider allows the use of a previously-generated, or known, time * when generating time-based UUIDs. diff --git a/src/UuidFactory.php b/src/UuidFactory.php index 6f2cea0..67ed8ee 100644 --- a/src/UuidFactory.php +++ b/src/UuidFactory.php @@ -43,6 +43,10 @@ use function unpack; use const STR_PAD_LEFT; +/** + * @deprecated UuidFactory will go away in ramsey/uuid version 5. Use dedicated + * factories for subtypes instead. + */ class UuidFactory implements UuidFactoryInterface { /** diff --git a/src/UuidFactoryInterface.php b/src/UuidFactoryInterface.php index 468cc63..e2a1236 100644 --- a/src/UuidFactoryInterface.php +++ b/src/UuidFactoryInterface.php @@ -14,117 +14,12 @@ declare(strict_types=1); namespace Ramsey\Uuid; -use DateTimeInterface; -use Ramsey\Uuid\Type\Hexadecimal; -use Ramsey\Uuid\Type\Integer as IntegerObject; -use Ramsey\Uuid\Validator\ValidatorInterface; - /** * UuidFactoryInterface defines common functionality all `UuidFactory` instances * must implement */ -interface UuidFactoryInterface +interface UuidFactoryInterface extends DeprecatedUuidFactoryInterface { - /** - * Returns the validator to use for the factory - * - * @psalm-mutation-free - */ - public function getValidator(): ValidatorInterface; - - /** - * Returns a version 1 (time-based) UUID from a host ID, sequence number, - * and the current time - * - * @param Hexadecimal|int|string|null $node A 48-bit number representing the - * hardware address; this number may be represented as an integer or a - * hexadecimal string - * @param int|null $clockSeq A 14-bit number used to help avoid duplicates - * that could arise when the clock is set backwards in time or if the - * node ID changes - * - * @return UuidInterface A UuidInterface instance that represents a - * version 1 UUID - */ - public function uuid1($node = null, ?int $clockSeq = null): UuidInterface; - - /** - * Returns a version 2 (DCE Security) UUID from a local domain, local - * identifier, host ID, clock sequence, and the current time - * - * @param int $localDomain The local domain to use when generating bytes, - * according to DCE Security - * @param IntegerObject|null $localIdentifier The local identifier for the - * given domain; this may be a UID or GID on POSIX systems, if the local - * domain is person or group, or it may be a site-defined identifier - * if the local domain is org - * @param Hexadecimal|null $node A 48-bit number representing the hardware - * address - * @param int|null $clockSeq A 14-bit number used to help avoid duplicates - * that could arise when the clock is set backwards in time or if the - * node ID changes - * - * @return UuidInterface A UuidInterface instance that represents a - * version 2 UUID - */ - public function uuid2( - int $localDomain, - ?IntegerObject $localIdentifier = null, - ?Hexadecimal $node = null, - ?int $clockSeq = null - ): UuidInterface; - - /** - * Returns a version 3 (name-based) UUID based on the MD5 hash of a - * namespace ID and a name - * - * @param string|UuidInterface $ns The namespace (must be a valid UUID) - * @param string $name The name to use for creating a UUID - * - * @return UuidInterface A UuidInterface instance that represents a - * version 3 UUID - * - * @psalm-pure - */ - public function uuid3($ns, string $name): UuidInterface; - - /** - * Returns a version 4 (random) UUID - * - * @return UuidInterface A UuidInterface instance that represents a - * version 4 UUID - */ - public function uuid4(): UuidInterface; - - /** - * Returns a version 5 (name-based) UUID based on the SHA-1 hash of a - * namespace ID and a name - * - * @param string|UuidInterface $ns The namespace (must be a valid UUID) - * @param string $name The name to use for creating a UUID - * - * @return UuidInterface A UuidInterface instance that represents a - * version 5 UUID - * - * @psalm-pure - */ - public function uuid5($ns, string $name): UuidInterface; - - /** - * Returns a version 6 (ordered-time) UUID from a host ID, sequence number, - * and the current time - * - * @param Hexadecimal|null $node A 48-bit number representing the hardware - * address - * @param int|null $clockSeq A 14-bit number used to help avoid duplicates - * that could arise when the clock is set backwards in time or if the - * node ID changes - * - * @return UuidInterface A UuidInterface instance that represents a - * version 6 UUID - */ - public function uuid6(?Hexadecimal $node = null, ?int $clockSeq = null): UuidInterface; - /** * Creates a UUID from a byte string * @@ -137,18 +32,6 @@ interface UuidFactoryInterface */ public function fromBytes(string $bytes): UuidInterface; - /** - * Creates a UUID from the string standard representation - * - * @param string $uuid A hexadecimal string - * - * @return UuidInterface A UuidInterface instance created from a hexadecimal - * string representation - * - * @psalm-pure - */ - public function fromString(string $uuid): UuidInterface; - /** * Creates a UUID from a 128-bit integer string * @@ -162,21 +45,14 @@ interface UuidFactoryInterface public function fromInteger(string $integer): UuidInterface; /** - * Creates a UUID from a DateTimeInterface instance + * Creates a UUID from the string standard representation * - * @param DateTimeInterface $dateTime The date and time - * @param Hexadecimal|null $node A 48-bit number representing the hardware - * address - * @param int|null $clockSeq A 14-bit number used to help avoid duplicates - * that could arise when the clock is set backwards in time or if the - * node ID changes + * @param string $uuid A hexadecimal string * - * @return UuidInterface A UuidInterface instance that represents a - * version 1 UUID created from a DateTimeInterface instance + * @return UuidInterface A UuidInterface instance created from a hexadecimal + * string representation + * + * @psalm-pure */ - public function fromDateTime( - DateTimeInterface $dateTime, - ?Hexadecimal $node = null, - ?int $clockSeq = null - ): UuidInterface; + public function fromString(string $uuid): UuidInterface; }