mirror of
https://github.com/ramsey/uuid.git
synced 2026-06-26 17:46:38 +03:00
Prepare for 4.0.0 release
This commit is contained in:
Ben Ramsey
+263
-1
@@ -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 <http://gh.peabody.io/uuidv6/>,
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user