A PHP library for generating universally unique identifiers (UUIDs).

Ben Ramsey

Last update: Jan 8, 2023

Related tags

Strings php uuid php7 guid identifiers

Overview

ramsey/uuid

A PHP library for generating and working with UUIDs.

ramsey/uuid is a PHP library for generating and working with universally unique identifiers (UUIDs).

This project adheres to a Contributor Code of Conduct. By participating in this project and its community, you are expected to uphold this code.

Much inspiration for this library came from the Java and Python UUID libraries.

Installation

The preferred method of installation is via Composer. Run the following command to install the package and add it as a requirement to your project's composer.json:

composer require ramsey/uuid

Upgrading to Version 4

See the documentation for a thorough upgrade guide:

Upgrading ramsey/uuid Version 3 to 4

Documentation

Please see https://uuid.ramsey.dev for documentation, tips, examples, and frequently asked questions.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

Coordinated Disclosure

Keeping user information safe and secure is a top priority, and we welcome the contribution of external security researchers. If you believe you've found a security issue in software that is maintained in this repository, please read SECURITY.md for instructions on submitting a vulnerability report.

ramsey/uuid for Enterprise

Available as part of the Tidelift Subscription.

The maintainers of ramsey/uuid and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use. Learn more.

Copyright and License

Comments

Uuid:uuid4() collisions

We are generating about 1M UUID4 a day, and we are getting several hundred collisions a day, such as:

[2015-08-26 21:29:19 +0200] [production-onebipws-1.apache - 17819] [DEBUG] [Request] 
time_total=0.145
"request_id":"fdfb98c1-4367-4f22-b68a-d7cdaedcc069" 

[2015-08-27 00:36:16 +0200] [production-onebipws-1.apache - 17819] [DEBUG] [Request] 
time_total=0.016
"request_id":"fdfb98c1-4367-4f22-b68a-d7cdaedcc069"

The issue seem to be correlated with the same Apache process regenerating the same UUID after several hours. It also seem to be correlated with particular EC2 machines which presents the problem.

We checked to have openssl_random_pseudo_bytes and if it was using a strong algorithm:

root@dev-all-onebip:~/projects/.../onebip-ultimate$  (master) # php -r "var_dump(function_exists('openssl_random_pseudo_bytes'));"                                      
bool(true)
root@dev-all-onebip:~/projects/.../onebip-ultimate$  (master) # php -r 'openssl_random_pseudo_bytes(16, $strong); var_dump($strong);'
bool(true)

How can we debug this problem?

bug

opened by giorgiosironi 98

Moontoast Math is abandoned

After performing a composer update this morning, I received this message in the terminal:

Package moontoast/math is abandoned, you should avoid using it. Use brick/math instead

I'm not certain if brick/math is a drop-in replacement, but thought you should know.
question informational

opened by alphametric 36
Implemented timestamp first and timestamp last comb generators

I know @aztech-dev is already working on this as per issue #86 and it's possible that his implementation will be more complete. The goal of this patch is to provide a quick implementation for combs usable with MySQL. I did not take little endian systems into account.

BC may be affected too, because I refactored the comb generator implementation using the template pattern and replaced the conditional with polymorphism (passing a type into the CombGenerator constructor would have lead to conditional code and breaking of the open/closed principle with each new comb variation).

opened by ghola 33
Performance drop

Hi there,

Today I've compared UUID generations with 2.8 vs 3.0 and noticed ~2.5x performance drop.

Pls check gist https://gist.github.com/jaymecd/7dbac8908bacf54b6db6 for more details.

opened by jaymecd 30
Unsupported declare 'strict_types'

Parse Error in function.php at 34

Warning: Unsupported declare 'strict_types' in /home/austonadmin/public_html/backOfficeAPI/vendor/ramsey/uuid/src/functions.php on line 14

Parse error: syntax error, unexpected '?', expecting variable (T_VARIABLE) in /home/austonadmin/public_html/backOfficeAPI/vendor/ramsey/uuid/src/functions.php on line 34

function v1($node = null, ?int $clockSeq = null): string { return Uuid::uuid1($node, $clockSeq)->toString(); }

On the Server PHP version is 7.3.
bug

opened by MuhammadSaim 25
Change namespace to "Ramsey"

I've received a fair amount of feedback from people about the "Rhumsaa" namespace. Apparently, it causes confusion and makes it difficult to find my packages. On more than one occasion, I've received reports that I have misspelled my namespace (the assumption is that the vendor name of the namespace should be "Ramsey" and I have misspelled it as "Rhumsaa").

In the 3.0 release, I am considering changing the package name to "ramsey/uuid" and the root namespace to "Ramsey."

I'm opening this up for comments to get feedback from those who are using this package. I want to make the upgrade transition as smooth as possible, and I'd like to hear whether this will significantly impact people using "rhumsaa/uuid."
enhancement

opened by ramsey 20

Improve preloading compatibility on 8.x

We have a preloading compiled and this is the only library that is reported at runtime errors.

2021-09-01 21:05:00.742 EEST<br />
Default
2021-09-01 21:05:00.742 EEST<b>Warning</b>: Can't preload unlinked class Ramsey\Uuid\Provider\Time\SystemTimeProvider: Unknown type dependencies in <b>/var/www/html/vendor/ramsey/uuid/src/Provider/Time/SystemTimeProvider.php</b> on line <b>25</b><br />
Default
2021-09-01 21:05:00.742 EEST<br />
Default
2021-09-01 21:05:00.742 EEST<b>Warning</b>: Can't preload unlinked class Ramsey\Uuid\Provider\Node\FallbackNodeProvider: Unknown type dependencies in <b>/var/www/html/vendor/ramsey/uuid/src/Provider/Node/FallbackNodeProvider.php</b> on line <b>25</b><br />
Default
2021-09-01 21:05:00.742 EEST<br />
Default
2021-09-01 21:05:00.742 EEST<b>Warning</b>: Can't preload unlinked class Ramsey\Uuid\Lazy\LazyUuidFromString: Unknown type dependencies in <b>/var/www/html/vendor/ramsey/uuid/src/Lazy/LazyUuidFromString.php</b> on line <b>53</b><br />
Default
2021-09-01 21:05:00.742 EEST<br />
Default
2021-09-01 21:05:00.742 EEST<b>Warning</b>: Can't preload unlinked class Ramsey\Uuid\Provider\Dce\SystemDceSecurityProvider: Unknown type dependencies in <b>/var/www/html/vendor/ramsey/uuid/src/Provider/Dce/SystemDceSecurityProvider.php</b> on line <b>36</b><br />
Default
2021-09-01 21:05:00.742 EEST<br />
Default
2021-09-01 21:05:00.742 EEST<b>Warning</b>: Can't preload unlinked class Ramsey\Uuid\Uuid: Unknown type dependencies in <b>/var/www/html/vendor/ramsey/uuid/src/Uuid.php</b> on line <b>41</b><br />
Default
2021-09-01 21:05:00.742 EEST<br />
Default
2021-09-01 21:05:00.742 EEST<b>Warning</b>: Can't preload unlinked class Ramsey\Uuid\Converter\Time\PhpTimeConverter: Unknown type dependencies in <b>/var/www/html/vendor/ramsey/uuid/src/Converter/Time/PhpTimeConverter.php</b> on line <b>43</b><br />
Default
2021-09-01 21:05:00.742 EEST<br />

bug

opened by pentium10 18

Could not convert database value "11ead97b-ffa1-7458-a..." to Doctrine Type uuid_binary_ordered_time. Expected format: UuidV1

Describe the bug

For the last couple of weeks I've noticed that in symfony UuidOrderedTimeGenerator is generating other than v1 Uuids intead of the expected v1, and that leads to throwing a converter error when validating the value

Exception message: Could not convert database value "xxxxxxxx-xxxx-xxxx-x..." to Doctrine Type uuid_binary_ordered_time. Expected format: UuidV1

To Reproduce...

Setup a new symfony project with registration and authentication:

composer create-project symfony/website-skeleton symf cd symf composer require ramsey/uuid-doctrine composer require symfonycasts/verify-email-bundle bin/console make:user bin/console make:registration-form during this process choose to login automatically on registration success bin/console make:auth
Basic project configuration:

Follow instructions given by make:auth to fix the return in onAuthenticationSuccess to a valid route (use bin/console make:controller DefaultController to create an empty controller to use here) change config/packages/ramsey._uuid_doctrine.yaml to be:

doctrine:
    dbal:
        types:
            uuid: 'Ramsey\Uuid\Doctrine\UuidType'
            uuid_binary: 'Ramsey\Uuid\Doctrine\UuidBinaryType'
            uuid_binary_ordered_time: 'Ramsey\Uuid\Doctrine\UuidBinaryOrderedTimeType'
        mapping_types:
            uuid_binary: binary
            uuid_binary_ordered_time: binary

In src/Entity/User.php change the type of $id to uuid

use \Ramsey\Uuid\UuidInterface;
....
/**
 * @ORM\Id()
 * @ORM\Column(type="uuid_binary_ordered_time", unique=true)
 * @ORM\GeneratedValue(strategy="CUSTOM")
 * @ORM\CustomIdGenerator(class="Ramsey\Uuid\Doctrine\UuidOrderedTimeGenerator")
 */
private $id;
...
public function getId(): ?UuidInterface
{
    return $this->id;
}

change .env so that `MAILER_DSN` and `DATABASE_URL` are both set and valid according to your own mail and database servers (i'm using my ISP's mail server and mariadb-10.4.7 in my test)

Prepare your database:

bin/console doctrine:migrations:diff bin/console doctrine:migrations:migrate
Run symfony's server or setup a vhost and go to the registration page http:///register in a browser. Fill out the form and click the register button
See output similar to the following:

on registration success a new entry is added to the user table in the database but during the login process the following exception is thrown and unhandled
```
Could not convert database value "11ead97b-ffa1-7458-a..." to Doctrine Type uuid_binary_ordered_time. Expected format: UuidV1
```

Examining the value of the id it is not in fact validated as version 1

Expected behavior

A new entry is added to the user table in the database using the information typed in the form, login suing those credentials and redirect to the route setup in onAuthenticationSuccess .

Screenshots or output

Symfony Exception
ConversionException
HTTP 500 Internal Server Error
Could not convert database value "11ead97b-ffa1-7458-a..." to Doctrine Type uuid_binary_ordered_time. Expected format: UuidV1

in vendor/ramsey/uuid-doctrine/src/UuidBinaryOrderedTimeType.php :: conversionFailedFormat (line 190)

        {
            if (1 !== $value->getVersion()) { 
                throw ConversionException::conversionFailedFormat(
                    $value->toString(),
                    self::NAME,
                    self::ASSERT_FORMAT
                );
            }
        }
        /**

in vendor/ramsey/uuid-doctrine/src/UuidBinaryOrderedTimeType.php -> assertUuidV1 (line 204)

         *
         * @throws ConversionException
         */
        private function encode(UuidInterface $uuid)
        {
            $this->assertUuidV1($uuid);
            return $this->getCodec()->encodeBinary($uuid);
        }
        /**

in vendor/ramsey/uuid-doctrine/src/UuidBinaryOrderedTimeType.php -> encode (line 108)

            if ($value === null || $value === '') {
                return null;
            }
            if ($value instanceof UuidInterface) {
                return $this->encode($value);  
            }
            try {
                if (is_string($value) || method_exists($value, '__toString')) {
                    $uuid = $this->getUuidFactory()->fromString((string) $value);

Environment details

OS: Linux (Ubuntu 20.04)
PHP version: 7.4.5
ramsey/uuid version: 4.1.0
ramsey/uuid-doctrine version: 1.6.0
ramsey/collection version: 1.0.1

Additional context

This started happenning a couple of weeks back when i updated ramsey/uuid using composer update - can't remember what version i had before

bug

opened by 537mfb 18

Sequential UUIDs

Any plans for COMBs? http://en.wikipedia.org/wiki/Globally_unique_identifier#Sequential_algorithms http://www.codeproject.com/Articles/388157/GUIDs-as-fast-primary-keys-under-multiple-database http://www.informit.com/articles/article.aspx?p=25862
enhancement

opened by ghola 17
Refactoring for #1 & #34

This is the same as #38, but against 3.0 branch.

As discussed in #1 & #34, this is a rough implementation of the discussed changes:

Extract new factory methods to work with GUID's Extract classes for PRNG Extract string/encoding decoding into "Codec" classes (one default impl, one Guid impl) Remove final keyword on Uuid class Extract 32-bit related exception throwing into subclass of Uuid Extract UuidFactory class, and extract all factory methods to that class (static factory methods are kept on Uuid class but simply delegate the call to a UuidFactory) Remove @covers from Uuid tests (to get more accurate coverage via XDebug) Remove tests covering internal Uuid methods Add some unit tests for new classes
enhancement

opened by fabre-thibaud 16
Allow passing null value to Uuid validators
Description

Upgrading from 3.x to 4.x introduces a breaking change in the api of Uuid::isValid in that it will no longer accept null as input.

With these changes null is now once again accepted as input to Uuid::isValid with the obvious result false.

Motivation and context

We use your library extensively to check that various string|null values are valid uuids in our code base. While upgrading to 4.x we noticed that some of these calls, namely those passing in null, would fail at runtime.

How has this been tested?

I have not tested this beyond the additional test input in the relevant XValidatorTest files.

Types of changes

[ ] Bug fix (non-breaking change which fixes an issue)

[x] New feature (non-breaking change which adds functionality)

[ ] Breaking change (fix or feature that would cause existing functionality to change)

PR checklist

[ ] My change requires a change to the documentation.

[ ] I have updated the documentation accordingly.

[x] I have read the CONTRIBUTING.md document.

[x] I have added tests to cover my changes.
opened by kalanzai 14
Is there a way to force Uuid serialize to string instead of bytes ?
Is there a way to force Uuid serialize to string instead of bytes ?

When I serialize an object containing uuid properties, these uuid values are serialized as bytes. Exemple produced serialized uuid:

"Application\Entity\CCDL2":2:{s:5:" * id";O:16:"Ramsey\Uuid\Uuid":1:{s:5:"bytes";s:16:"???x?Nh??X?Y?x";}

I'm getting issues when trying to unserialize data because binary values are stored and unproperly handled by sgbd or unproperly serialized by php. So the better way should be to serialize as string by default as I don't need to store the value as binary.
question
opened by e-belair 4
Misused Psalm Assertion for isValid() method?

Do I misunderstand the @psalm-assert-if-true Assertion?

The Uuid::isValid method has a psalm assertion @psalm-assert-if-true non-empty-string $uuid set. This assertion seems to lead Psalm to think that only non-empty-strings can be given to this method and any false validation means that the given string is empty.
At least that's what I'm guessing after receiving the following error All possible types for this argument were invalidated - This may be dead code in a project of mine.

Example code

Here's a simplified version of the problematic code. I've just mocked a Uuid::isValid implementation for demo purposes.

https://psalm.dev/r/764e8e9309
question

opened by LikeAJohny 1
How to search a partial uuid?

My transactions table uses a uuid which is stored as bytes in the database.

I would like to know how to search for a partial uuid? Obviously, since we are using bytes, the data is stored as a binary in the table so in theory I need to convert the partial uuid string to a binary and then to search on that.

Is there anyway to do this natively with UUID?

If I had a full UUID, I am simply going to use something like so:

$qb->andWhere('transactions.uuid = :uuid')->setParameter('uuid', Uuid::fromString($options['transactionUuid'])->getBytes());

But to search a partial uuid, I am looking to do something as follows:

$qb->expr()->like('transaction.uuid', Uuid:fromString(':search')->getBytes()),

But obviously the fromString requires a correctly formed uuid string as apposed to a partial.

I am not sure this is possible and perhaps is one of the downfalls of using bytes in the table as apposed to string.
question

opened by chateaux 0
$PHP fatal error: Class Brick\Math\RoundingMode not found$

PHP fatal error: Class Brick\Math\RoundingMode not found

Description

I'm not sure what's happening, the class is present in the directory, but out of the blue I started getting this RoundingMode class not found error.

Steps to reproduce

I just try and run the app that uses the Ramsey UUID package.

Expected behavior

it just runs up until today

Screenshots or output

Fatal error: Uncaught Error: Class "Brick\Math\RoundingMode" not found in /Users/galentucker/Dropbox/Business/Provident Enterprises/PGE_htdocs/PGEBingo/vendor/ramsey/uuid/src/FeatureSet.php:167 Stack trace: #0 /Users/galentucker/Dropbox/Business/Provident Enterprises/PGE_htdocs/PGEBingo/vendor/ramsey/uuid/src/UuidFactory.php(108): Ramsey\Uuid\FeatureSet->__construct() #1 /Users/galentucker/Dropbox/Business/Provident Enterprises/PGE_htdocs/PGEBingo/vendor/ramsey/uuid/src/Uuid.php(406): Ramsey\Uuid\UuidFactory->__construct() #2 /Users/galentucker/Dropbox/Business/Provident Enterprises/PGE_htdocs/PGEBingo/vendor/ramsey/uuid/src/Uuid.php(668): Ramsey\Uuid\Uuid::getFactory() #3 /Users/galentucker/Dropbox/Business/Provident Enterprises/PGE_htdocs/PGEBingo/Core/Classes/BingoSheet.php(141): Ramsey\Uuid\Uuid::uuid6()

Environment details

I'm running in PHP Storm on MacOS 12.5, with MAMP Pro 6.6.2. PHP version 8.1.0

Additional context

Nothing changed in my environment to my knowledge. It was working, and today... this. I've tried updating to the latest UUID 4.4.0 using composer. didn't help.
bug

opened by ingenuityon 1

__unserialize() fails for existing sessions

__unserialize() fails for existing user sessions because 'bytes' isn't set.

Description

We get the following error:

ValueError: Ramsey\Uuid\Uuid::__unserialize(): Argument #1 ($data) is invalid #15 /vendor/ramsey/uuid/src/Uuid.php(333): Ramsey\Uuid\Uuid::__unserialize #14 [internal](0): unserialize #13 /vendor/symfony/security-http/Firewall/ContextListener.php(312): Symfony\Component\Security\Http\Firewall\ContextListener::safelyUnserialize #12 /vendor/symfony/security-http/Firewall/ContextListener.php(126): Symfony\Component\Security\Http\Firewall\ContextListener::authenticate #11 /vendor/symfony/security-http/Firewall/AbstractListener.php(26): Symfony\Component\Security\Http\Firewall\AbstractListener::__invoke #10 /vendor/symfony/security-http/Firewall.php(119): Symfony\Component\Security\Http\Firewall::callListeners #9 /vendor/symfony/security-http/Firewall.php(92): Symfony\Component\Security\Http\Firewall::onKernelRequest #8 /vendor/symfony/event-dispatcher/EventDispatcher.php(270): Symfony\Component\EventDispatcher\EventDispatcher::Symfony\Component\EventDispatcher\{closure} #7 /vendor/symfony/event-dispatcher/EventDispatcher.php(230): Symfony\Component\EventDispatcher\EventDispatcher::callListeners #6 /vendor/symfony/event-dispatcher/EventDispatcher.php(59): Symfony\Component\EventDispatcher\EventDispatcher::dispatch #5 /vendor/symfony/http-kernel/HttpKernel.php(128): Symfony\Component\HttpKernel\HttpKernel::handleRaw #4 /vendor/symfony/http-kernel/HttpKernel.php(74): Symfony\Component\HttpKernel\HttpKernel::handle #3 /vendor/symfony/http-kernel/Kernel.php(202): Symfony\Component\HttpKernel\Kernel::handle #2 /vendor/symfony/runtime/Runner/Symfony/HttpKernelRunner.php(35): Symfony\Component\Runtime\Runner\Symfony\HttpKernelRunner::run #1 /vendor/autoload_runtime.php(35): require_once #0 /public/index.php(18): null

In our Symfony 5 application we got that error after upgrading to Ramsey/UUID 4 for sessions that where still logged in. It is because off https://github.com/ramsey/uuid/commit/0997de99a2a2ce27f6b5a913dcb26442ab61a6c8 is this error expected? As it is a major update from 3.x to 4.x, if that is the case I don't see this mentioned in the changelog.

For us this means we have to logout every user who is logged in now. So that they won't encounter this error

Steps to reproduce

1: Symfony 5 installation with security and logged in user and Ramsey/UUID 3.x 2: upgrade Ramsey/UUID to 4.x 3. See error for __unserialize()

Environment details

PHP version: we are using 8.0

bug

opened by JohJohan 3

$Ramsey\Uuid\Uuid::uuid6() is not an instance of Ramsey\Uuid\Nonstandard\UuidV6 anymore$

Ramsey\Uuid\Uuid::uuid6() is not an instance of Ramsey\Uuid\Nonstandard\UuidV6 anymore

hello as said in the title, this : $uuid = Ramsey\Uuid\Uuid::uuid6() ; $uuid instanceof Ramsey\Uuid\Nonstandard\UuidV6 now returns false...

if i do get_class($uuid), i'll get : Ramsey\Uuid\Lazy\LazyUuidFromString object...

since i would prefer to be sure to have the time ordered Uuid, is it something i still can check somehow ?

opened by haclong 2

Releases(4.7.1)

4.7.1(Dec 31, 2022)
Fixed

Allow the use of ramsey/collection ^2.0 with ramsey/uuid.

Source code(tar.gz)
Source code(zip)
4.7.0(Dec 19, 2022)
Added

Add Uuid::fromHexadecimal() and UuidFactory::fromHexadecimal(). These methods are not required by the interfaces.

Fixed

Ignore MAC addresses consisting of all zeroes (i.e., 00:00:00:00:00:00).

Source code(tar.gz)
Source code(zip)
3.9.7(Dec 19, 2022)
Fixed

Add #[ReturnTypeWillChange] to Uuid::jsonSerialize() method.

Source code(tar.gz)
Source code(zip)
4.6.0(Nov 5, 2022)
Added

Add support for version 8, custom UUIDs, as defined in draft-ietf-uuidrev-rfc4122bis-00, section 5.8. While still an Internet-Draft, version 8 is stable and unlikely to change in any way that breaks compatibility.

Use Ramsey\Uuid\Uuid::uuid8() to generate version 8 UUIDs.

Version 8 UUIDs are of type Ramsey\Uuid\Rfc4122\UuidV8.

The constant Ramsey\Uuid\Uuid::UUID_TYPE_CUSTOM exists for version 8 UUIDs.

Fixed

Ensure monotonicity of version 7 UUIDs.

Source code(tar.gz)
Source code(zip)
4.5.1(Sep 16, 2022)
Fixed

Update RFC 4122 validator to recognize version 6 and 7 UUIDs.

Source code(tar.gz)
Source code(zip)
4.5.0(Sep 15, 2022)
Added

Promote version 6, reordered time UUIDs from the Nonstandard namespace to the Rfc4122 namespace. Version 6 UUIDs are defined in New UUID Formats, section 5.1. While still an Internet-Draft version 6 is stable and unlikely to change in any way that breaks compatibility.

Add support for version 7, Unix Epoch time UUIDs, as defined in New UUID Formats, section 5.2. While still an Internet-Draft, version 7 is stable and unlikely to change in any way that breaks compatibility.

Use Ramsey\Uuid\Uuid::uuid7() to generate version 7 UUIDs.

Version 7 UUIDs are of type Ramsey\Uuid\Rfc4122\UuidV7.

The constant Ramsey\Uuid\Uuid::UUID_TYPE_UNIX_TIME exists for version 7 UUIDs.

Add Ramsey\Uuid\Converter\Time\UnixTimeConverter and Ramsey\Uuid\Generator\UnixTimeGenerator to support version 7 UUID generation.

Add support for max UUIDs through Ramsey\Uuid\Uuid::MAX and Ramsey\Uuid\Rfc4122\MaxUuid.

Changed

The lowest version of brick/math allowed is now ^0.8.8.

Deprecated

The following will be removed in ramsey/uuid 5.0.0:

Ramsey\Uuid\Nonstandard\UuidV6 is deprecated in favor of Ramsey\Uuid\Rfc4122\UuidV6.

Ramsey\Uuid\Uuid::UUID_TYPE_PEABODY; use Ramsey\Uuid\Uuid::UUID_TYPE_REORDERED_TIME instead.

Fixed

For Ramsey\Uuid\Uuid::isValid(), Psalm now asserts the UUID is a non-empty-string when it is valid.

Nil UUIDs are properly treated as RFC 4122 variants, and getVariant() now returns a 2 when called on a nil UUID.

Source code(tar.gz)
Source code(zip)
4.4.0(Aug 5, 2022)
Changed

Allow brick/math 0.10.

Remove dev dependency to moontoast/math.

Un-deprecate UuidInterface::getUrn().

Source code(tar.gz)
Source code(zip)
4.3.1(Mar 27, 2022)
Deprecated

The following will be removed in ramsey/uuid 5.0.0:

Ramsey\Uuid\Generator\RandomLibAdapter

Source code(tar.gz)
Source code(zip)
4.3.0(Mar 26, 2022)
Changed

Remove support for PHP 7.2, 7.3, and 7.4. This is not a BC break, since Composer will do the right thing for your environment and select a compatible version of this library.

Require ext-ctype extension. For applications that run in environments where the ext-ctype is not present, please require a polyfill, such as symfony/polyfill-ctype.

Use iterable<UuidBuilderInterface> instead of BuilderCollection types.

Use iterable<NodeProviderInterface> instead of NodeProviderCollection types.

Deprecated

The following will be removed in ramsey/uuid 5.0.0:

Ramsey\Uuid\Builder\BuilderCollection

Ramsey\Uuid\Provider\Node\NodeProviderCollection

Dependency on ramsey/collection

Fixed

Support valid UUIDs in uppercase in LazyUuidFromString.

Source code(tar.gz)
Source code(zip)
4.2.3(Sep 25, 2021)
Fixed

Switch back to ^8.0 in the PHP version requirement.

Source code(tar.gz)
Source code(zip)
4.1.3(Sep 25, 2021)
Fixed

Switch back to ^8.0 in the PHP version requirement.

Source code(tar.gz)
Source code(zip)
4.0.3(Sep 25, 2021)
Fixed

Switch back to ^8.0 in the PHP version requirement.

Source code(tar.gz)
Source code(zip)
3.9.6(Sep 25, 2021)
Fixed

Switch back to ^8.0 in the PHP version requirement.

Source code(tar.gz)
Source code(zip)
4.2.2(Sep 24, 2021)
Fixed

Indicate support for PHP 8.1, using ~8.1.0 to prevent installations on 8.2 until the library is ready.

Source code(tar.gz)
Source code(zip)
4.1.2(Sep 24, 2021)
Fixed

Lock 4.1.x to ~8.0.0 to indicate it does not support PHP 8.1.

Source code(tar.gz)
Source code(zip)
4.0.2(Sep 24, 2021)
Fixed

Lock 4.0.x to ~8.0.0 to indicate it does not support PHP 8.1.

Source code(tar.gz)
Source code(zip)
3.9.5(Sep 24, 2021)
Fixed

Indicate support for PHP 8.1, using ~8.1.0 to prevent installations on 8.2 until the library is ready.

Source code(tar.gz)
Source code(zip)
4.2.1(Aug 11, 2021)
Fixed

Fix soft BC break with Uuid::fromString() signature. The change from string to non-empty-string on the parameter annotation introduced a BC break for those using static analysis tools. This release reverts this change and provides an assertion to guard against empty strings. See ramsey/uuid#383.

Source code(tar.gz)
Source code(zip)
4.2.0(Aug 6, 2021)
Added

Add Ramsey\Uuid\Exception\UuidExceptionInterface for all ramsey/uuid exceptions to implement. See ramsey/uuid#340.

Fixed

Fix serialization of UUIDs. See ramsey/uuid#361.

Source code(tar.gz)
Source code(zip)
3.9.4(Aug 6, 2021)
Fixed

Allow installation of paragonie/random_compat v9.99.100 (for PHP 8 compatibility).

Source code(tar.gz)
Source code(zip)
4.1.1(Aug 18, 2020)
Fixed

Allow use of brick/math version 0.9

Source code(tar.gz)
Source code(zip)
4.1.0(Jul 28, 2020)
Changed

Improve performance of Uuid::fromString(), Uuid::fromBytes(), UuidInterface#toString(), and UuidInterface#getBytes(). See PR #324 for more information.

Source code(tar.gz)
Source code(zip)
4.0.1(Mar 29, 2020)
Fixed

Fix collection deserialization errors due to upstream allowed_classes being set to false. For details, see ramsey/uuid#303 and ramsey/collection#47.

Source code(tar.gz)
Source code(zip)
4.0.0(Mar 22, 2020)
Read the upgrade guide for details on how these changes may impact your code and what you can do to ease the upgrade process.

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 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.

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.

Source code(tar.gz)
Source code(zip)
4.0.0-beta2(Mar 1, 2020)
Added

Add missing convenience methods for Rfc4122\UuidV2.

Add Provider\Node\StaticNodeProvider to assist in setting a custom static node value with the multicast bit set for version 1 UUIDs.

Changed

Provider\NodeProviderInterface::getNode() now returns Type\Hexadecimal instead of string|false|null.

Source code(tar.gz)
Source code(zip)
4.0.0-beta1(Feb 27, 2020)
Added

Add ValidatorInterface::getPattern() to return the regular expression pattern used by the validator.

Add v6() helper function for version 6 UUIDs.

Changed

Set the pattern constants on validators as private. Use the getPattern() method instead.

Change the $node parameter for UuidFactoryInterface::uuid6() to accept null or Type\Hexadecimal.

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.

Removed

Remove currentTime() method from Provider\Time\FixedTimeProvider and Provider\Time\SystemTimeProvider; it had previously been removed from Provider\TimeProviderInterface.

Source code(tar.gz)
Source code(zip)
4.0.0-alpha5(Feb 23, 2020)
Added

Introduce Builder\BuilderCollection and Provider\Node\NodeProviderCollection.

Changed

Builder\FallbackBuilder now accepts only a Builder\BuilderCollection as its constructor parameter.

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.

Source code(tar.gz)
Source code(zip)
4.0.0-alpha4(Feb 23, 2020)
Added

Add a Type\TypeInterface that each of the ramsey/uuid types implements.

Support version 6 UUIDs; see http://gh.peabody.io/uuidv6/.

Changed

Rename Type\IntegerValue to Type\Integer. It was originally named IntegerValue because static analysis sees Integer in docblock annotations and treats it as the native int type. Integer is not a reserved word in PHP, so it should be named Integer for consistency with other types in this library. When using it, a class alias prevents static analysis from complaining.

Mark Guid\Guid and Nonstandard\Uuid classes as final.

Add uuid6() method to UuidFactoryInterface.

Deprecated

Uuid::UUID_TYPE_IDENTIFIER is deprecated. Use Uuid::UUID_TYPE_DCE_SECURITY instead.

Uuid::VALID_PATTERN is deprecated. Use Validator\GenericValidator::VALID_PATTERN instead.

Source code(tar.gz)
Source code(zip)
4.0.0-alpha3(Feb 21, 2020)
Fixed

Fix microsecond rounding error on 32-bit systems.

Source code(tar.gz)
Source code(zip)
4.0.0-alpha2(Feb 21, 2020)
Added

Add Uuid::fromDateTime() to create version 1 UUIDs from instances of \DateTimeInterface.

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.

Changed

Add fromDateTime() method to UuidFactoryInterface.

Change UuidInterface::getHex() to return a Ramsey\Uuid\Type\Hexadecimal instance.

Change UuidInterface::getInteger() to return a Ramsey\Uuid\Type\IntegerValue instance.

Fixed

Round microseconds to six digits when getting DateTime from v1 UUIDs. This circumvents a needless exception for an otherwise valid time-based UUID.

Source code(tar.gz)
Source code(zip)