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