About

The intent of UUIDs is to enable distributed systems to uniquely identify information without significant central coordination. In this context the word unique should be taken to mean “practically unique” rather than “guaranteed unique”. Since the identifiers have a finite size, it is possible for two differing items to share the same identifier. The identifier size and generation process need to be selected so as to make this sufficiently improbable in practice. Anyone can create a UUID and use it to identify something with reasonable confidence that the same identifier will never be unintentionally created by anyone to identify something else. Information labeled with UUIDs can therefore be later combined into a single database without needing to resolve identifier (ID) conflicts.

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

Installation

The preferred method of installation is via Packagist and 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 from 2.x to 3.x

While we have made significant internal changes to the library, we have made every effort to ensure a seamless upgrade path from the 2.x series of this library to 3.x.

One major breaking change is the transition from the Rhumsaa root namespace to Ramsey. In most cases, all you will need is to change the namespace to Ramsey in your code, and everything will “just work.”

Here are full details on the breaking changes to the public API of this library:

All namespace references of Rhumsaa have changed to Ramsey. Simply change the namespace to Ramsey in your code and everything should work.

The console application has moved to ramsey/uuid-console. If using the console functionality, use Composer to require ramsey/uuid-console.

The Doctrine field type mapping has moved to ramsey/uuid-doctrine. If using the Doctrine functionality, use Composer to require ramsey/uuid-doctrine.

What to do if you see a “rhumsaa/uuid is abandoned” message

When installing your project’s dependencies using Composer, you might see the following message:

Package rhumsaa/uuid is abandoned, you should avoid using it. Use ramsey/uuid instead.

Don’t panic. Simply execute the following commands with Composer:

composer remove rhumsaa/uuid

composer require ramsey/uuid=^2.9

After doing so, you will have the latest ramsey/uuid package in the 2.x series, and there will be no need to modify any code; the namespace in the 2.x series is still Rhumsaa.

Requirements

Some methods in this library have requirements due to integer size restrictions on 32-bit and 64-bit builds of PHP. A 64-bit build of PHP and the Moontoast\Math library are recommended. However, this library is designed to work on 32-bit builds of PHP without Moontoast\Math, with some degraded functionality. Please check the API documentation for more information.

If a particular requirement is not present, then an UnsatisfiedDependencyException is thrown, allowing one to catch a bad call in an environment where the call is not supported and gracefully degrade.

Introducing ramsey/uuid

It seems quite absurd for me to introduce ramsey/uuid, a library that saw its 1.0.0 release on July 19, 2012, and is now at version 3.4.1, having had 35 releases since its first, but what’s even more ludicrous is that I haven’t once blogged about this library. I mention it only in passing in my “Dates Are Hard” post. So, allow me to introduce you to perhaps a familiar face, an old friend, the ramsey/uuid library for PHP.

Dates Are Hard

I recently encountered an issue when calculating the time for an RFC 4122 UUID that had me questioning the accuracy of our modern, accepted calendars, especially with regard to the days of the week on which our dates fall.