Skip to content

[Uid] Default to UuidV7 when using UuidFactory #21408

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 26, 2025
Merged

[Uid] Default to UuidV7 when using UuidFactory #21408

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 48 additions & 36 deletions components/uid.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,8 +158,42 @@ following methods to create a ``Uuid`` object from it::
$uuid = Uuid::fromBase58('TuetYWNHhmuSQ3xPoVLv9M');
$uuid = Uuid::fromRfc4122('d9e7a184-5d5b-11ea-a62a-3499710062d0');

You can also use the ``UuidFactory`` to generate UUIDs. First, you may
configure the behavior of the factory using configuration files::
You can also use the ``UuidFactory`` to generate UUIDs. Inject the factory in
your services and use it as follows:

namespace App\Service;

use Symfony\Component\Uid\Factory\UuidFactory;

class FooService
{
public function __construct(
private UuidFactory $uuidFactory,
) {
}

public function generate(): void
{
$uuid = $this->uuidFactory->create();

$randomBasedUuid = $this->uuidFactory->randomBased()->create();
// $namespace can be omitted if a default namespace is configured in the factory (see below)
$nameBasedUuid = $this->uuidFactory->nameBased($namespace)->create($name);
// $node can be omitted if a default node is configured in the factory (see below)
$timestampBased = $this->uuidFactory->timeBased($node)->create();

// ...
}
}

By default, this factory generates the folllowing UUIDs:

* Default and time-based UUIDs: UUIDv7
* Name-based UUIDs: UUIDv5
* Random-based UUIDs: UUIDv4
* Time-based node and UUID namespace: ``null``

You can configure these default values::

.. configuration-block::

Expand All @@ -168,10 +202,10 @@ configure the behavior of the factory using configuration files::
# config/packages/uid.yaml
framework:
uid:
default_uuid_version: 7
name_based_uuid_version: 5
default_uuid_version: 6
name_based_uuid_version: 3
name_based_uuid_namespace: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
time_based_uuid_version: 7
time_based_uuid_version: 6
time_based_uuid_node: 121212121212

.. code-block:: xml
Expand All @@ -187,10 +221,10 @@ configure the behavior of the factory using configuration files::

<framework:config>
<framework:uid
default_uuid_version="7"
name_based_uuid_version="5"
default_uuid_version="6"
name_based_uuid_version="6"
name_based_uuid_namespace="6ba7b810-9dad-11d1-80b4-00c04fd430c8"
time_based_uuid_version="7"
time_based_uuid_version="6"
time_based_uuid_node="121212121212"
/>
</framework:config>
Expand All @@ -209,41 +243,19 @@ configure the behavior of the factory using configuration files::

$container->extension('framework', [
'uid' => [
'default_uuid_version' => 7,
'name_based_uuid_version' => 5,
'default_uuid_version' => 6,
'name_based_uuid_version' => 3,
'name_based_uuid_namespace' => '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
'time_based_uuid_version' => 7,
'time_based_uuid_version' => 6,
'time_based_uuid_node' => 121212121212,
],
]);
};

Then, you can inject the factory in your services and use it to generate UUIDs based
on the configuration you defined::

namespace App\Service;

use Symfony\Component\Uid\Factory\UuidFactory;

class FooService
{
public function __construct(
private UuidFactory $uuidFactory,
) {
}

public function generate(): void
{
// This creates a UUID of the version given in the configuration file (v7 by default)
$uuid = $this->uuidFactory->create();

$nameBasedUuid = $this->uuidFactory->nameBased(/** ... */);
$randomBasedUuid = $this->uuidFactory->randomBased();
$timestampBased = $this->uuidFactory->timeBased();
.. versionadded:: 7.4

// ...
}
}
Starting from Symfony 7.4, the default version for both UUIDs and time-based
UUIDs is v7. In previous versions, the default was v6.

Converting UUIDs
~~~~~~~~~~~~~~~~
Expand Down