Cover of the book Symfony 5: The Fast Track

Symfony 5: The Fast Track is the best book to learn modern Symfony development, from zero to production. +300 pages showcasing Symfony with Docker, APIs, queues & async tasks, Webpack, SPAs, etc.

New in Symfony 5.3: UID Improvements

Symfony 5.3 is backed by JoliCode. JoliCode is a team of passionate developers and open-source lovers, with a strong expertise in PHP & Symfony technologies. They can help you build your projects using state-of-the-art practices.

The UID Component was introduced in Symfony 5.1 as an experimental feature to help you generate and work with UIDs (universally unique identifiers) such as UUIDs and ULIDs. In Symfony 5.3 this component is no longer considered experimental and we added some new features to it.

New Ways to Generate UIDs

Contributed by
Thomas Calvet
in #39507 and #39850.

Creating UID values is easy thanks to methods like Uuid::v1(), Uuid::v4(), new Ulid(), etc. In Symfony 5.3 we’ve added new methods so you can create UID objects from several string representations of UIDs:

1
2
3
4
5
6
7
8
9
$uuid = Uuid::fromBinary("\xd9\xe7\xa1\x84\x5d\x5b\x11\xea\xa6\x2a\x34\x99\x71\x00\x62\xd0");
$uuid = Uuid::fromBase32('6SWYGR8QAV27NACAHMK5RG0RPG');
$uuid = Uuid::fromBase58('TuetYWNHhmuSQ3xPoVLv9M');
$uuid = Uuid::fromRfc4122('d9e7a184-5d5b-11ea-a62a-3499710062d0');

$ulid = Ulid::fromBinary("\x01\x71\x06\x9d\x59\x3d\x97\xd3\x8b\x3e\x23\xd0\x6d\xe5\xb3\x08");
$ulid = Ulid::fromBase32('01E439TP9XJZ9RPFH3T1PYBCR8');
$ulid = Ulid::fromBase58('1BKocMc5BnrVcuq2ti4Eqm');
$ulid = Ulid::fromRfc4122('0171069d-593d-97d3-8b3e-23d06de5b308');

In addition, we’ve added several services such as ulid.factory and uuid.factory (and their corresponding autowiring aliases UlidFactory, UuidFactory, etc.) so you can customize the creation of UIDs. The defaults of the generated UIDs are now configured semantically:

1
2
3
4
# config/packages/framework.yaml
framework:
    uid:
        default_uuid_version: 4

Finally, we added UlidGenerator and UuidGenerator classes so you can use them as Doctrine ID generators, to use UIDs as the value of your primary keys in Doctrine entities.

UID Form Types

Contributed by
Gemorroj
in #39863.

The integration with the Form component was one of the last missing features of the UIDs. That’s why in Symfony 5.3 we’ve added the UuidType and UlidType form types so you can work with UID values in your forms.

These form types render a <input type="text"> field with the string representation of the given UID object and transform it back to a UID object when submitting the form.

Serializing UIDs

Contributed by
Thomas Calvet
in #39675.

The Serializer component includes a UidNormalizer to transform objects of type Symfony\Component\Uid\AbstractUid into strings. In Symfony 5.3 we’ve improved it to support different string formats.

You can now pass the UidNormalizer::NORMALIZATION_FORMAT_KEY context option to the serializer and set it to the desired format (e.g. UidNormalizer::NORMALIZATION_FORMAT_RFC_4122, etc.)

Generate and Inspect UIDs in the Console

Contributed by
Thomas Calvet
in #39883.

The UID component now includes some console commands to help you generate and inspect the details of UUID/ULID values.

Read the UID command docs to learn how to enable these commands in your application before using them:

1
2
3
4
5
6
$ php bin/console uuid:generate --random-based
$ php bin/console ulid:generate --count=2 --format=rfc4122

# run them with the `--help` option to check all their options:
$ php bin/console uuid:generate --help
$ php bin/console ulid:generate --help
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
$  php bin/console ulid:inspect 01F2TTCSYK1PDRH73Z41BN1C4X
  --------------------- --------------------------------------
   Label                 Value
  --------------------- --------------------------------------
   Canonical (Base 32)   01F2TTCSYK1PDRH73Z41BN1C4X
   Base 58               1BYGm16jS4kX3VYCysKKq6
   RFC 4122              0178b5a6-67d3-0d9b-889c-7f205750b09d
  --------------------- --------------------------------------
   Timestamp             2021-04-09 08:01:24.947
  --------------------- --------------------------------------
Help the Symfony project!

As with any Open-Source project, contributing code or documentation is the most common way to help, but we also have a wide range of sponsoring opportunities.

Comments

@Javier we should mention that the last commands needs to be enabled by the user to be usable.
@Oskar you are right. However, instead of explaining that here, I've added a link to the new docs which explain it in detail. Thanks!
@Javier personally I use https://github.com/ramsey/uuid or https://github.com/ramsey/uuid-doctrine for a long time and it's totally seamless for me to use "fromString" and "toString" for working with most common UUID form. Till today I didn't know that it's RFC 4122. It could be confusing to force people to get used to use "fromRfc4122" instead of simple "fromString" even if I understand it's correct from totally pedantic point of view.

But what I'm wondering about is fromBase32 and fromBase58 - I use the base conversion for shortening UUIDs and hashed data quite often, but mostly base36 (0-9a-z) useful for case insensitive environment like default Doctrine ORM columns collation and base62 (0-9a-zA-Z) for places where case sensitive comparison works well (https://github.com/epk-technologies/epk-symfony-bundle/tree/main/src/Utils). Why did you choose base 32 and 58 and what are the advantages against base 36 and 62 except the result will be longer?
@Javier It might be good to mention that when generating several ULIDs within one millisecond the randomness of the "random" portion is only one bit different between successive ULIDs.

This is not obvious behaviour from reading the documentation of the component where one might assume that the random bits are random for each generated ULID. The specification does explain in under the Monotonicity section, but if one just reads the Sorting section (which states that within the same millisecond, sort order is not guaranteed) then it would be unexpected.
@Jan there is already toString and fromString methods actually. The new ones were added when one wants to be explicit about which exact base they want to use.
About base32 vs 36: because 32 is ULID's canonical representation, and because it's easier to compute. About base58 vs 62: because this prevents using confusing letters "0OIl" - an idea that comes from bitcoin addresses. In terms of length, this changes nothing in practice.

@David you're right, this is in line with the ULID spec. The note about monotonicity within the same ms relates to parallel server processes, which are each going to select a different random offset. But within the same process, ULID encourages simply incrementing the random offset by one each time.
Login with SymfonyConnect to post a comment