diff --git a/CHANGELOG.md b/CHANGELOG.md index f366e18..fbfdb46 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,267 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Security +## [4.0.0] - 2020-03-17 + +### Added + +* Add support for version 6 UUIDs, as defined by , + including the static method `Uuid::uuid6()`, which returns a + `Nonstandard\UuidV6` instance. +* 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 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 classes to represent version 6 UUIDs, GUIDs, and nonstandard + (non-RFC 4122 variant) UUIDs: + * `Nonstandard\UuidV6` + * `Guid\Guid` + * `Nonstandard\Uuid` +* Add `Uuid::fromDateTime()` to create version 1 UUIDs from instances of + `\DateTimeInterface`. +* The `\DateTimeInterface` instance returned by `UuidInterface::getDateTime()` + (and now `Rfc4122\UuidV1::getDateTime()`) now includes microseconds, as + specified by the version 1 UUID. +* Add `Validator\ValidatorInterface` and `Validator\GenericValidator` to allow + flexibility in validating UUIDs/GUIDs. + * The default validator continues to validate UUID strings using the same + relaxed validation pattern found in the 3.x series of ramsey/uuid. + * Introduce `Rfc4122\Validator` that may be used for strict validation of + RFC 4122 UUID strings. + * Add ability to change the default validator used by `Uuid` through + `FeatureSet::setValidator()`. + * Add `getValidator()` and `setValidator()` to `UuidFactory`. +* Add `Provider\Node\StaticNodeProvider` to assist in setting a custom static + node value with the multicast bit set for version 1 UUIDs. +* Add the following new exceptions: + * `Exception\BuilderNotFoundException` - + Thrown to indicate that no suitable UUID builder could be found. + * `Exception\DateTimeException` - + Thrown to indicate that the PHP DateTime extension encountered an + exception/error. + * `Exception\DceSecurityException` - + Thrown to indicate an exception occurred while dealing with DCE Security + (version 2) UUIDs. + * `Exception\InvalidArgumentException` - + Thrown to indicate that the argument received is not valid. This extends the + built-in PHP `\InvalidArgumentException`, so there should be no BC breaks + with ramsey/uuid throwing this exception, if you are catching the PHP + exception. + * `Exception\InvalidBytesException` - + Thrown to indicate that the bytes being operated on are invalid in some way. + * `Exception\NameException` - + Thrown to indicate that an error occurred while attempting to hash a + namespace and name. + * `Exception\NodeException` - + Throw to indicate that attempting to fetch or create a node ID encountered + an error. + * `Exception\RandomSourceException` - + Thrown to indicate that the source of random data encountered an error. + * `Exception\TimeSourceException` - + Thrown to indicate that the source of time encountered an error. + * `Exception\UnableToBuildUuidException` - + Thrown to indicate a builder is unable to build a 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. +* Add `Rfc4122\UuidInterface` to specifically represent RFC 4122 variant UUIDs. +* Add `Rfc4122\UuidBuilder` to build RFC 4122 variant UUIDs. This replaces the + existing `Builder\DefaultUuidBuilder`, which is now deprecated. +* Introduce `Math\CalculatorInterface` for representing calculators to perform + arithmetic operations on integers. +* Depend on [brick/math](https://github.com/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. +* Introduce `Type\Hexadecimal`, `Type\Integer`, `Type\Decimal`, and `Type\Time` + for improved type-safety when dealing with arbitrary string values. +* Add a `Type\TypeInterface` that each of the ramsey/uuid types implements. +* 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. +* Introduce `Builder\BuilderCollection` and `Provider\Node\NodeProviderCollection`. + These are typed collections for providing builders and node providers to + `Builder\FallbackBuilder` and `Provider\Node\FallbackNodeProvider`, respectively. +* 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](https://pecl.php.net/package/uuid). + +### Changed + +* Set minimum required PHP version to 7.2. +* This library now works on 32-bit and 64-bit systems, with no degradation in + functionality. +* By default, the following static methods will now return 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` +* 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`. +* 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. +* Change `Uuid::getFields()` to return an instance of `Fields\FieldsInterface`. + Previously, it returned an array of integer values (on 64-bit systems only). +* `Uuid::getDateTime()` now returns an instance of `\DateTimeImmutable` instead + of `\DateTime`. +* Make the following changes to `UuidInterface`: + * `getHex()` now returns a `Type\Hexadecimal` instance. + * `getInteger()` now returns a `Type\Integer` instance. The `Type\Integer` + instance holds 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. + * `getDateTime()` now returns `\DateTimeInterface` instead of `\DateTime`. + * Add `__toString()` method. + * Add `getFields()` method. It returns an instance of `Fields\FieldsInterface`. +* Add the following new methods to `UuidFactoryInterface`: + * `uuid2()` + * `uuid6()` + * `fromDateTime()` + * `fromInteger()` + * `getValidator()` +* This library no longer throws generic exceptions. However, this should not + result in BC breaks, since the new exceptions extend from built-in PHP + exceptions that this library previously threw. + * `Exception\UnsupportedOperationException` is now descended from + `\LogicException`. Previously, it descended from `\RuntimeException`. +* Change required constructor parameters for `Uuid`: + * Change the first required constructor parameter for `Uuid` from + `array $fields` to `Rfc4122\FieldsInterface $fields`. + * Add `Converter\TimeConverterInterface $timeConverter` as the fourth + required constructor parameter for `Uuid`. +* 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. +* Add `Converter\TimeConverterInterface $timeConverter` as the second required + constructor parameter for `Rfc4122\UuidBuilder`. This also affects the + now-deprecated `Builder\DefaultUuidBuilder`, since this class now inherits + from `Rfc4122\UuidBuilder`. +* Add `convertTime()` method to `Converter\TimeConverterInterface`. +* Add `getTime()` method to `Provider\TimeProviderInterface`. It replaces the + `currentTime()` method. +* `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. +* `Provider\NodeProviderInterface::getNode()` now returns `Type\Hexadecimal` + instead of `string|false|null`. +* `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 `NumberConverterInterface` to accept and return string values + instead of `mixed`; this simplifies the interface and makes it consistent. +* `Generator\DefaultTimeGenerator` no longer adds the variant and version bits + to the bytes it returns. These must be applied to the bytes afterwards. +* 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()`. + +### 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. You may use the new `Math\CalculatorInterface::toIntegerValue()` + method to convert the `Type\Hexadecimal` instances to instances of + `Type\Integer`. This library provides `Math\BrickMathCalculator`, which may be + used for this purpose, or you may use the arbitrary-precision arithemetic + library of your choice. + * `getClockSeqHiAndReserved()` + * `getClockSeqLow()` + * `getClockSequence()` + * `getNode()` + * `getTimeHiAndVersion()` + * `getTimeLow()` + * `getTimeMid()` + * `getTimestamp()` +* `getDateTime()` on `UuidInterface` and `Uuid` is deprecated. Use this method + only on instances of `Rfc4122\UuidV1` or `Nonstandard\UuidV6`. +* `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`. +* 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 systems. + * `Builder\DegradedUuidBuilder` + * `Converter\Number\DegradedNumberConverter` + * `Converter\Time\DegradedTimeConverter` + * `DegradedUuid` +* The `Uuid::UUID_TYPE_IDENTIFIER` constant is deprecated. Use + `Uuid::UUID_TYPE_DCE_SECURITY` instead. +* The `Uuid::VALID_PATTERN` constant is deprecated. Use + `Validator\GenericValidator::getPattern()` or `Rfc4122\Validator::getPattern()` + instead. + +### 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. +* Remove the method `Provider\TimeProviderInterface::currentTime()`. Use + `Provider\TimeProviderInterface::getTime()` instead. + + ## [4.0.0-beta2] - 2020-03-01 ## Added @@ -912,7 +1173,8 @@ versions leading up to this release.* [ramsey/uuid-doctrine]: https://github.com/ramsey/uuid-doctrine [ramsey/uuid-console]: https://github.com/ramsey/uuid-console -[unreleased]: https://github.com/ramsey/uuid/compare/4.0.0-beta2...HEAD +[unreleased]: https://github.com/ramsey/uuid/compare/4.0.0...HEAD +[4.0.0]: https://github.com/ramsey/uuid/compare/4.0.0-beta2...4.0.0 [4.0.0-beta2]: https://github.com/ramsey/uuid/compare/4.0.0-beta1...4.0.0-beta2 [4.0.0-beta1]: https://github.com/ramsey/uuid/compare/4.0.0-alpha5...4.0.0-beta1 [4.0.0-alpha5]: https://github.com/ramsey/uuid/compare/4.0.0-alpha4...4.0.0-alpha5