Id handling with value objects in Symfony

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 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 for the id is automatically registered.

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 CQRS bundle to have serialized ids there.

Doctrine types

To use an id in your entities, you just need to register a new type for the id. Create a new class for the new id like the following:

<?php

declare(strict_types=1);

namespace App\Doctrine;

use App\ValueObject\UserId;
use DigitalCraftsman\Ids\Doctrine\IdType;

final class UserIdType extends IdType
{
    public static function getTypeName(): string
    {
        return 'user_id';
    }

    public static function getClass(): string
    {
        return UserId::class;
    }
}

Then register the new type in your config/packages/doctrine.yaml file:

doctrine:
  dbal:
    types:
      user_id: App\Doctrine\UserIdType

Alternatively you can also add a compiler pass to register the types automatically.

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

<?php

declare(strict_types=1);

namespace App\Entity;

use App\ValueObject\UserId;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
use Symfony\Component\Security\Core\User\UserInterface;

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

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 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 for the id list is automatically registered.

Doctrine types

To use an id list in your entities, you just need to register a new type for the id list. Create a new class for the new id list like the following:

<?php

declare(strict_types=1);

namespace App\Doctrine;

use App\ValueObject\UserId;
use App\ValueObject\UserIdList;
use DigitalCraftsman\Ids\Doctrine\IdListType;

final class UserIdListType extends IdListType
{
    protected function getTypeName(): string
    {
        return 'user_id_list';
    }

    protected function getIdListClass(): string
    {
        return UserIdList::class;
    }
    
    protected function getIdClass(): string
    {
        return UserId::class;
    }
}

Then register the new type in your config/packages/doctrine.yaml file:

doctrine:
  dbal:
    types:
      user_id_list: App\Doctrine\UserIdListType

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(repositoryClass: InvestorRepository::class)]
#[ORM\Table(name: 'investor')]
class Investor
{
    #[ORM\Column(name: 'ids_of_users_with_access', type: 'user_id_list')]
    public UserIdList $idsOfUsersWithAccess;
    
    ...
}

Additional documentation

Using with binary(16)

I am currently stuck with a problem I do not yet see a solution: I have database entries with binary(16) which are for now Symfony Uuid primary keys. The problem with that is, that I can't always define the "uuid" type for a doctrine query parameter to make it work. Otherwise, it will just use the string representation to query the database and won't find anything. I need to either specify the parameter type or use the binary representation of the uuid directly as the parameter value.

So i installed this library and defined the IdType and overrid this methods:

    public function getSQLDeclaration(array $column, AbstractPlatform $platform): string
    {
        $column['length'] = 16;
        $column['fixed'] = true;

        return $platform->getBinaryTypeDeclarationSQL($column);
    }

    public function getBindingType()
    {
        return ParameterType::BINARY;
    }

    public function convertToDatabaseValue($value, AbstractPlatform $platform): ?string
    {
        if (null === $value) {
            return null;
        }

        if (is_string($value)) {
            return Uuid::fromString($value)->toBinary();
        }

        if ($value instanceof Id) {
            return Uuid::fromString((string) $value)->toBinary();
        }
    }

    public function convertToPHPValue($value, AbstractPlatform $platform): ?Id
    {
        if (null === $value) {
            return null;
        }

        return $this->getIdClass()::fromBinary($value);
    }

Not pretty, but does the job. Now when I use the query builder like this:

    $result = $this->createQueryBuilder('a')
            ->andWhere('a.relation = :relation')
            ->setParameter('relation', $relationEntityObject)
            ->getQuery()
            ->getResult()
        ;

I still do not get the result as the generated query still using the string representation and not the binary (as I was expecting with the convertToDatabaseValue method.

Does anyone have an idea what I am missing?

digital-craftsman-de / ids Goto Github PK

ids's Introduction

Id handling with value objects in Symfony

Installation and configuration

Working with ids

Creating a new id

Symfony serializer

Doctrine types

Working with id lists

Creating a new id list

Symfony serializer

Doctrine types

Additional documentation

ids's People

Contributors

Stargazers

Forkers

ids's Issues

Changes

Recommend Projects

Recommend Topics

Recommend Org