README

A Symfony bundle to work with id and id list value objects in Symfony. It includes Symfony normalizers for automatic normalization and denormalization and Doctrine types to store the ids and id lists directly in the database.

As it's a central part of an application, it's tested thoroughly (including mutation testing).

Installation and configuration

Install package through composer:

composer require digital-craftsman/ids

It's recommended that you install the uuid PHP extension for better performance of id creation and validation. symfony/polyfill-uuid is used as a fallback. You can prevent installing the polyfill when you've installed the PHP extension.

Working with ids

Creating a new id

The bulk of the logic is in the Id class. Creating a new id is as simple as creating a new final readonly class and extending from it like the following:

<?php

declare(strict_types=1);

namespace App\ValueObject;

use DigitalCraftsman\Ids\ValueObject\Id;

final readonly class UserId extends Id
{
}

Now you're already able to use it in your code like this:

$userId = UserId::generateRandom();

if ($userId->isEqualTo($command->userId)) {
    ...
}

Guard against invalid usages:

$requestingUser->userId->mustNotBeEqualTo($command->targetUserId);

Or with a custom exception:

$requestingUser->userId->mustNotBeEqualTo(
    $command->targetUserId,
    static fn () => new Exception\UserCanNotTargetItself(),
);

Symfony serializer

If you're injecting the SerializerInterface directly, there is nothing to do. The normalizer from digital-craftsman/self-aware-normalizers are registered automatically and will handle the serialization and deserialization of the Id class, as it implements the StringNormalizable interface.

namespace App\DTO;

final readonly class UserPayload
{
    public function __construct(
        public UserId $userId,
        public string $firstName,
        public string $lastName,
    ) {
    }
}

public function __construct(
    private SerializerInterface $serializer,
) {
}

public function handle(UserPayload $userPayload): string
{
    return $this->serializer->serialize($userPayload, JsonEncoder::FORMAT);
}

{
  "userId": "15d6208b-7cf2-49e5-a193-301d594d98a7",
  "firstName": "Tomas",
  "lastName": "Bauer"
}

This can be combined with the CQS bundle to have serialized ids there.

Doctrine types

To use an id in your entities, you just need to make sure that the directory your id is in, is added in the self_aware_normalizers.implementation_directories configuration of self-aware-normalizers.php. They are then automatically registered with the relevant doctrine type and can be used directly with it's class name.

<?php

declare(strict_types=1);

namespace App\Entity;

use App\ValueObject\UserId;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity()]
#[ORM\Table(name: '`user`')]
class User
{
    #[ORM\Id]
    #[ORM\Column(name: 'id', type: UserId::class)]
    public UserId $userId;
    
    ...
}

Working with id lists

Id lists are wrapper for an array of ids. They contain a few utility functions and improved type safety.

The IdList is immutable. Therefore, the mutation methods (like add, remove, ...) always return a new instance of the list.

Creating a new id list

The bulk of the logic is in the IdList class. Creating a new id list is as simple as creating a new final readonly class and extending from it like the following:

<?php

declare(strict_types=1);

namespace App\ValueObject;

use DigitalCraftsman\Ids\ValueObject\IdList;

/** @extends IdList<UserId> */
final readonly class UserIdList extends IdLIst
{
    public static function handlesIdClass(): string
    {
        return UserId::class;
    }
}

Now you're already able to use it in your code like this:

$userIdList = new UserIdList($userIds);

if ($idsOfEnabledUsers->contains($command->userId)) {
    ...
}

Guard against invalid usages:

$idsOfEnabledUsers->mustContainId($command->targetUserId);

Or with custom exception:

$idsOfEnabledUsers->mustContainId(
    $command->targetUserId,
    static fn () => new Exception\UserIsNotEnabled(),
);

Symfony serializer

If you're injecting the SerializerInterface directly, there is nothing to do. The normalizer from digital-craftsman/self-aware-normalizers are registered automatically and will handle the serialization and deserialization of the IdList class, as it implements the ArrayNormalizable interface.

Doctrine types

Same as with the ids, you just have to make sure that the directory the id list is in, is part of the self_aware_normalizers.implementation_directories configuration of self-aware-normalizers.php.

Then you're already able to add it into your entity like this:

<?php

declare(strict_types=1);

namespace App\Entity;

use App\ValueObject\UserIdList;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity()]
#[ORM\Table(name: 'investor')]
class Investor
{
    ...
    
    #[ORM\Column(name: 'ids_of_users_with_access', type: UserIdList::class)]
    public UserIdList $idsOfUsersWithAccess;
    
    ...
}

Additional documentation

• Prevent polyfill usage
• Use other UUID versions
• Changelog
• Upgrade guide