Version 5: Name-based (SHA-1)

Danger

Since version 3 and version 5 UUIDs essentially use a salt (the namespace) to hash data, it may be tempting to use them to hash passwords. DO NOT do this under any circumstances! You should not store any sensitive information in a version 3 or version 5 UUID, since MD5 and SHA-1 are insecure and have known attacks demonstrated against them. Use these types of UUIDs as identifiers only.

The first thing that comes to mind with most people think of a UUID is a random identifier, but name-based UUIDs aren’t random at all. In fact, they’re deterministic. For any given identical namespace and name, you will always generate the same UUID.

Name-based UUIDs are useful when you need an identifier that’s based on something’s name — think identity — and will always be the same no matter where or when it is created.

For example, let’s say I want to create an identifier for a URL. I could use a version 1 or version 4 UUID to create an identifier for the URL, but what if I’m working with a distributed system, and I want to ensure that every client in this system can always generate the same identifier for any given URL?

This is where a name-based UUID comes in handy.

Name-based UUIDs combine a namespace with a name. This way, the UUIDs are unique to the namespace they’re created in. RFC 4122 defines some predefined namespaces, one of which is for URLs.

Note

Version 5 UUIDs use SHA-1 as the hashing algorithm for combining the namespace and the name.

Generate a version 5, name-based UUID for a URL
use Ramsey\Uuid\Uuid;

$uuid = Uuid::uuid5(Uuid::NAMESPACE_URL, 'https://www.php.net');

The UUID generated will always be the same, as long as the namespace and name are the same. The version 5 UUID for “https://www.php.net” in the URL namespace will always be a8f6ae40-d8a7-58f0-be05-a22f94eca9ec. See for yourself. Run the code above, and you’ll see it always generates the same UUID.

Tip

Version 5 UUIDs generated in ramsey/uuid are instances of UuidV5. Check out the Ramsey\Uuid\Rfc4122\UuidV5 API documentation to learn more about what you can do with a UuidV5 instance.

Custom Namespaces

If you’re working with name-based UUIDs for names that don’t fit into any of the predefined namespaces, or you don’t want to use any of the predefined namespaces, you can create your own namespace.

The best way to do this is to generate a version 1 or version 4 UUID and save this UUID as your namespace.

Generate a custom namespace UUID
use Ramsey\Uuid\Uuid;

$uuid = Uuid::uuid1();

printf("My namespace UUID is %s\n", $uuid->toString());

This will generate a version 1, Gregorian time UUID, which we’ll store to a constant so we can reuse it as our own custom namespace.

Use a custom namespace to create version 5, name-based UUIDs
use Ramsey\Uuid\Uuid;

const WIDGET_NAMESPACE = '4bdbe8ec-5cb5-11ea-bc55-0242ac130003';

$uuid = Uuid::uuid5(WIDGET_NAMESPACE, 'widget/1234567890');

With this custom namespace, the version 5 UUID for the name “widget/1234567890” will always be a35477ae-bfb1-5f2e-b5a4-4711594d855f.

We can publish this namespace, allowing others to use it to generate identifiers for widgets. When two or more systems try to reference the same widget, they’ll end up generating the same identifier for it, which is exactly what we want.