The UID Component

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

use Symfony\Component\Uid\Uuid;

// UUID type 1 generates the UUID using the MAC address of your device and a timestamp.
// Both are obtained automatically, so you don't have to pass any constructor argument.
$uuid = Uuid::v1(); // $uuid is an instance of Symfony\Component\Uid\UuidV1

// UUID type 4 generates a random UUID, so you don't have to pass any constructor argument.
$uuid = Uuid::v4(); // $uuid is an instance of Symfony\Component\Uid\UuidV4

// UUID type 3 and 5 generate a UUID hashing the given namespace and name. Type 3 uses
// MD5 hashes and Type 5 uses SHA-1. The namespace is another UUID (e.g. a Type 4 UUID)
// and the name is an arbitrary string (e.g. a product name; if it's unique).
$namespace = Uuid::v4();
$name = $product->getUniqueName();

$uuid = Uuid::v3($namespace, $name); // $uuid is an instance of Symfony\Component\Uid\UuidV3
$uuid = Uuid::v5($namespace, $name); // $uuid is an instance of Symfony\Component\Uid\UuidV5

// the namespaces defined by RFC 4122 (see https://tools.ietf.org/html/rfc4122#appendix-C)
// are available as PHP constants and as string values
$uuid = Uuid::v3(Uuid::NAMESPACE_DNS, $name);  // same as: Uuid::v3('dns', $name);
$uuid = Uuid::v3(Uuid::NAMESPACE_URL, $name);  // same as: Uuid::v3('url', $name);
$uuid = Uuid::v3(Uuid::NAMESPACE_OID, $name);  // same as: Uuid::v3('oid', $name);
$uuid = Uuid::v3(Uuid::NAMESPACE_X500, $name); // same as: Uuid::v3('x500', $name);

// UUID type 6 is not yet part of the UUID standard. It's lexicographically sortable
// (like ULIDs) and contains a 60-bit timestamp and 63 extra unique bits.
// It's defined in https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html#name-uuid-version-6
$uuid = Uuid::v6(); // $uuid is an instance of Symfony\Component\Uid\UuidV6

// UUID version 7 features a time-ordered value field derived from the well known
// Unix Epoch timestamp source: the number of seconds since midnight 1 Jan 1970 UTC, leap seconds excluded.
// As well as improved entropy characteristics over versions 1 or 6.
$uuid = Uuid::v7();

// UUID version 8 provides an RFC-compatible format for experimental or vendor-specific use cases.
// The only requirement is that the variant and version bits MUST be set as defined in Section 4:
// https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html#variant_and_version_fields
// UUIDv8 uniqueness will be implementation-specific and SHOULD NOT be assumed.
$uuid = Uuid::v8();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

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();

        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

use Symfony\Component\Uid\NilUuid;
use Symfony\Component\Uid\Uuid;

// checking if the UUID is null (note that the class is called
// NilUuid instead of NullUuid to follow the UUID standard notation)
$uuid = Uuid::v4();
$uuid instanceof NilUuid; // false

// checking the type of UUID
use Symfony\Component\Uid\UuidV4;
$uuid = Uuid::v4();
$uuid instanceof UuidV4; // true

// getting the UUID datetime (it's only available in certain UUID types)
$uuid = Uuid::v1();
$uuid->getDateTime(); // returns a \DateTimeImmutable instance

// checking if a given value is valid as UUID
$isValid = Uuid::isValid($uuid); // true or false

// comparing UUIDs and checking for equality
$uuid1 = Uuid::v1();
$uuid4 = Uuid::v4();
$uuid1->equals($uuid4); // false

// this method returns:
//   * int(0) if $uuid1 and $uuid4 are equal
//   * int > 0 if $uuid1 is greater than $uuid4
//   * int < 0 if $uuid1 is less than $uuid4
$uuid1->compare($uuid4); // e.g. int(4)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// src/Entity/Product.php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Symfony\Bridge\Doctrine\Types\UuidType;
use Symfony\Component\Uid\Uuid;

#[ORM\Entity(repositoryClass: ProductRepository::class)]
class Product
{
    #[ORM\Column(type: UuidType::NAME)]
    private Uuid $someProperty;

    // ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Symfony\Bridge\Doctrine\Types\UuidType;
use Symfony\Component\Uid\Uuid;

class User implements UserInterface
{
    #[ORM\Id]
    #[ORM\Column(type: UuidType::NAME, unique: true)]
    #[ORM\GeneratedValue(strategy: 'CUSTOM')]
    #[ORM\CustomIdGenerator(class: 'doctrine.uuid_generator')]
    private ?Uuid $id;

    public function getId(): ?Uuid
    {
        return $this->id;
    }

    // ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// src/Repository/ProductRepository.php

// ...
use Symfony\Bridge\Doctrine\Types\UuidType;

class ProductRepository extends ServiceEntityRepository
{
    // ...

    public function findUserProducts(User $user): array
    {
        $qb = $this->createQueryBuilder('p')
            // ...
            // add UuidType::NAME as the third argument to tell Doctrine that this is a UUID
            ->setParameter('user', $user->getUuid(), UuidType::NAME)

            // alternatively, you can convert it to a value compatible with
            // the type inferred by Doctrine
            ->setParameter('user', $user->getUuid()->toBinary())
        ;

        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

namespace App\Service;

use Symfony\Component\Uid\Factory\UlidFactory;

class FooService
{
    public function __construct(
        private UlidFactory $ulidFactory,
    ) {
    }

    public function generate(): void
    {
        $ulid = $this->ulidFactory->create();

        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

use Symfony\Component\Uid\Ulid;

$ulid1 = new Ulid();
$ulid2 = new Ulid();

// checking if a given value is valid as ULID
$isValid = Ulid::isValid($ulidValue); // true or false

// getting the ULID datetime
$ulid1->getDateTime(); // returns a \DateTimeImmutable instance

// comparing ULIDs and checking for equality
$ulid1->equals($ulid2); // false
// this method returns $ulid1 <=> $ulid2
$ulid1->compare($ulid2); // e.g. int(-1)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// src/Entity/Product.php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Symfony\Bridge\Doctrine\Types\UlidType;
use Symfony\Component\Uid\Ulid;

#[ORM\Entity(repositoryClass: ProductRepository::class)]
class Product
{
    #[ORM\Column(type: UlidType::NAME)]
    private Ulid $someProperty;

    // ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Symfony\Bridge\Doctrine\Types\UlidType;
use Symfony\Component\Uid\Ulid;

class Product
{
    #[ORM\Id]
    #[ORM\Column(type: UlidType::NAME, unique: true)]
    #[ORM\GeneratedValue(strategy: 'CUSTOM')]
    #[ORM\CustomIdGenerator(class: 'doctrine.ulid_generator')]
    private ?Ulid $id;

    public function getId(): ?Ulid
    {
        return $this->id;
    }

    // ...

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// src/Repository/ProductRepository.php

// ...
use Symfony\Bridge\Doctrine\Types\UlidType;

class ProductRepository extends ServiceEntityRepository
{
    // ...

    public function findUserProducts(User $user): array
    {
        $qb = $this->createQueryBuilder('p')
            // ...
            // add UlidType::NAME as the third argument to tell Doctrine that this is a ULID
            ->setParameter('user', $user->getUlid(), UlidType::NAME)

            // alternatively, you can convert it to a value compatible with
            // the type inferred by Doctrine
            ->setParameter('user', $user->getUlid()->toBinary())
        ;

        // ...
    }
}