ramsey/uuid

The 3.0.0 release represents a significant step for the ramsey/uuid library. While the simple and familiar API used in previous versions remains intact, this release provides greater flexibility to integrators, including the ability to inject your own number generators, UUID codecs, node and time providers, and more.

Please note: The changelog for 3.0.0 includes all notes from the alpha and beta versions leading up to this release.

Added

• Add a number of generators that may be used to override the library defaults for generating random bytes (version 4) or time-based (version 1) UUIDs
  • CombGenerator to allow generation of sequential UUIDs
  • OpenSslGenerator to generate random bytes on systems where openssl_random_pseudo_bytes() is present
  • MtRandGenerator to provide a fallback in the event other random generators are not present
  • RandomLibAdapter to allow use of [ircmaxell/random-lib]
  • RandomBytesGenerator for use with PHP 7; ramsey/uuid will default to use this generator when running on PHP 7
  • Refactor time-based (version 1) UUIDs into a TimeGeneratorInterface to allow for other sources to generate version 1 UUIDs in this library
  • PeclUuidTimeGenerator and PeclUuidRandomGenerator for creating version 1 or version 4 UUIDs using the pecl-uuid extension
• Add a setTimeGenerator method on UuidFactory to override the default time generator
• Add option to enable PeclUuidTimeGenerator via FeatureSet
• Support GUID generation by configuring a FeatureSet to use GUIDs
• Allow UUIDs to be serialized as JSON through JsonSerializable

Changed

• Change root namespace from "Rhumsaa" to "Ramsey;" in most cases, simply making this change in your applications is the only upgrade path you will need—everything else should work as expected
• No longer consider Uuid class as final; everything is now based around interfaces and factories, allowing you to use this package as a base to implement other kinds of UUIDs with different dependencies
• Return an object of type DegradedUuid on 32-bit systems to indicate that certain features are not available
• Default RandomLibAdapter to a medium-strength generator with [ircmaxell/random-lib]; this is configurable, so other generator strengths may be used

Removed

• Remove PeclUuidFactory in favor of using pecl-uuid with generators
• Remove timeConverter and timeProvider properties, setters, and getters in both FeatureSet and UuidFactory as those are now exclusively used by the default TimeGenerator
• Move UUID [Doctrine field type] to [ramsey/uuid-doctrine]
• Move uuid console application to [ramsey/uuid-console]
• Remove Uuid::VERSION package version constant

Fixed

• Improve GUID support to ensure that:
  • On little endian (LE) architectures, the byte order of the first three fields is LE
  • On big endian (BE) architectures, it is the same as a GUID
  • String representation is always the same
• Fix exception message for DegradedNumberConverter::fromHex()

Fixed

• Improve GUID support to ensure that:
  • On little endian (LE) architectures, the byte order of the first three fields is LE
  • On big endian (BE) architectures, it is the same as a GUID
  • String representation is always the same
• Fix exception message for DegradedNumberConverter::fromHex()

Added

• Enable use of custom TimeGenerator implementations
• Add a setTimeGenerator method on UuidFactory to override the default time generator
• Add option to enable PeclUuidTimeGenerator via FeatureSet

Removed

• Remove timeConverter and timeProvider properties, setters, and getters in both FeatureSet and UuidFactory as those are now exclusively used by the default TimeGenerator

Added

• Refactor time-based (version 1) UUIDs into a TimeGeneratorInterface to allow for other sources to generate version 1 UUIDs in this library
• Add PeclUuidTimeGenerator and PeclUuidRandomGenerator for creating version 1 or version 4 UUIDs using the pecl-uuid extension
• Add RandomBytesGenerator for use with PHP 7. ramsey/uuid will default to use this generator when running on PHP 7

Changed

• Default RandomLibAdapter to a medium-strength generator with [ircmaxell/random-lib]; this is configurable, so other generator strengths may be used

Removed

• Remove PeclUuidFactory in favor of using pecl-uuid with generators

Added

• Allow dependency injection through UuidFactory and/or extending FeatureSet to override any package defaults
• Add a number of generators that may be used to override the library defaults:
  • CombGenerator to allow generation of sequential UUIDs
  • OpenSslGenerator to generate random bytes on systems where openssql_random_pseudo_bytes() is present
  • MtRandGenerator to provide a fallback in the event other random generators are not present
  • RandomLibAdapter to allow use of [ircmaxell/random-lib]
• Support GUID generation by configuring a FeatureSet to use GUIDs
• Allow UUIDs to be serialized as JSON through JsonSerializable

Changed

• Change root namespace from "Rhumsaa" to "Ramsey;" in most cases, simply making this change in your applications is the only upgrade path you will need—everything else should work as expected
• No longer consider Uuid class as final; everything is now based around interfaces and factories, allowing you to use this package as a base to implement other kinds of UUIDs with different dependencies
• Return an object of type DegradedUuid on 32-bit systems to indicate that certain features are not available

Removed

• Move UUID [Doctrine field type] to [ramsey/uuid-doctrine]
• Move uuid console application to [ramsey/uuid-console]
• Remove Uuid::VERSION package version constant

Security

• Drop the use of OpenSSL as a fallback and use [paragonie/random_compat] to support RandomBytesGenerator in versions of PHP earlier than 7.0; this addresses and fixes the [collision issue]

Added

• Add support for symfony/console v3 in the uuid CLI application

Fixed

• Fix exception message in Uuid::calculateUuidTime()

Fixed

• Ensure the release tag makes it into the rhumsaa/uuid package

Fixed

• Use passthru() and output buffering in getIfconfig()
• Cache the system node in a static variable so that we process it only once per runtime

Added

• Add static fromInteger() method to create UUIDs from string integer or Moontoast\Math\BigNumber

Fixed

• Improve Doctrine conversion to Uuid or string for the ramsey/uuid [Doctrine field type]

Fixed

• Change loop in generateBytes() from foreach to for

Fixed

• Fix upper range for mt_rand used in version 4 UUIDs

Changed

• Upgrade to PSR-4 autoloading

Fixed

• Move moontoast/math and symfony/console to require-dev
• Support symfony/console 2.3 (LTS version)

Added

• Add Uuid::VALID_PATTERN constant containing a UUID validation regex pattern

Fixed

• Fix bug where uuid console application could not find the Composer autoloader when installed in another project

Added

• Introduce uuid console application for generating and decoding UUIDs from CLI (run ./bin/uuid for details)
• Add Uuid::getInteger() to retrieve a Moontoast\Math\BigNumber representation of the 128-bit integer representing the UUID
• Add Uuid::getHex() to retrieve the hexadecimal representation of the UUID
• Use netstat on Linux to capture the node for a version 1 UUID
• Require moontoast/math as part of the regular package requirements

Added

• Use openssl_random_pseudo_bytes(), if available, to generate random bytes

Added

• Return null from Uuid::getVersion() if the UUID isn't an RFC 4122 variant
• Support string UUIDs without dashes passed to Uuid::fromString()

Added

• Support creation of UUIDs from bytes with Uuid::fromBytes()

Added

• Add Doctrine\UuidType::requiresSQLCommentHint() method

Fixed

• Fix cases where the system node was coming back with uppercase hexadecimal digits; this ensures that case in the node is converted to lowercase

Fixed

• Fix bug in Uuid::isValid() where the NIL UUID was not reported as valid

Added

• Allow checking the validity of a UUID through the Uuid::isValid() method

Added

• Support UUID generation on 32-bit platforms

Changed

• Mark Uuid class final
• Require moontoast/math on 64-bit platforms for Uuid::getLeastSignificantBits() and Uuid::getMostSignificantBits(); the integers returned by these methods are unsigned 64-bit integers and unsupported even on 64-bit builds of PHP
• Move UnsupportedOperationException to the Exception subnamespace

Fixed

• Relax [Doctrine field type] conversion rules for UUIDs

Fixed

• Remove final keyword from Uuid class

Added

• Support ramsey/uuid UUIDs as a Doctrine Database Abstraction Layer (DBAL) field mapping type

Added

• Support generation of version 1, 3, 4, and 5 UUIDs