README

A Symfony bundle to enable value objects and DTOs to normalize and denormalize themselves through implementing simple interfaces that normalize to scalar values and denormalize themselves from scalar values (string, int, float, bool and array). Adding this kind of logic to the classes themselves might be considered a bad practice, but depending on the use case it will actually be better due to the fact that the data structure and the normalization need to be changed together.

The name implies that the value objects and DTOs are self-aware in the sense that they know how to normalize and denormalize themselves and that they are self-aware enough to do so 🙂

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/self-aware-normalizers

Optionally, you can add a self-aware-normalizers.php file to your config/packages. The options are described below.

Usage

Normalizers

To make the normalization process easier, there are the following normalizers included:

StringNormalizableNormalizer
IntNormalizableNormalizer
FloatNormalizableNormalizer
BoolNormalizableNormalizer
ArrayNormalizableNormalizer

Additionally, there is an interface for each of the normalizers. Every class that implements one of the interfaces, will be automatically normalized to the respected type. This means putting the logic of how serialization of a class works within the class. That's not really seen as a good practice. In my experience, the data structure and the normalization need to be changed together. So, I like it better to have both in one place. I've used this approach in multiple large scale projects for years and haven't had a single issue with it yet. But your mileage may vary.

With this you can have nested denormalization that looks like this:

/**
 * @psalm-type NormalizedSearch = array{
 *     searchTerm: string,
 *     limit: int,
 * }
 */
final readonly class Search implements ArrayNormalizable
{
    public function __construct(
        public SearchTerm $searchTerm,
        public Limit $limit,
    ) {
    }
    
    /**
    * @param NormalizedSearch $data
    */
    public static function denormalize(array $data): self
    {
        return new self(
            searchTerm: SearchTerm::denormalize($data['searchTerm']),
            limit: Limit::denormalize($data['limit']),
        );
    }
    
    /**
    * @return NormalizedSearch
    */
    public function normalize(): array
    {
        return [
            'searchTerm' => $this->searchTerm->normalize(),
            'limit' => $this->limit->normalize(),
        ];
    }
}

Denormalized for null handling

When handling null you can use the Nullable*Denormalizable interfaces with the related Nullable*DenormalizableTrait to handle switches between null and the class like the following:

/**
 * @psalm-type NormalizedSearchWithOptionalLimit = array{
 *     searchTerm: string,
 *     limit: int | null,
 * }
 */
final readonly class SearchWithOptionalLimit implements ArrayNormalizable
{
    public function __construct(
        public SearchTerm $searchTerm,
        public ?Limit $limit,
    ) {
    }
    
    /**
    * @param NormalizedSearchWithOptionalLimit $data
    */
    public static function denormalize(array $data): self
    {
        return new self(
            searchTerm: SearchTerm::denormalize($data['searchTerm']),
            limit: Limit::denormalizeWhenNotNull($data['limit']),
        );
    }
    
    /**
    * @return NormalizedSearchWithOptionalLimit
    */
    public function normalize(): array
    {
        return [
            'searchTerm' => $this->searchTerm->normalize(),
            'limit' => $this->limit?->normalize(),
        ];
    }
}

Internally the value object simply has to implement the relevant interface and use the related trait like the following:

final readonly class Limit implements IntNormalizable, NullableIntDenormalizable
{
    use NullableIntDenormalizableTrait;

    public function __construct(
        public int $limit,
        ...

Doctrine types

When using the normalizers, you can also use the same logic for doctrine types.

Automatic doctrine types

You don't even need to define custom doctrine types. All you need to do is to add the directory your implementing classes are into the config/packages/self-aware-normalizers.php configuration:

<?php

declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\App;

return App::config([
    'self_aware_normalizers' => [
        'implementation_directories' => [
            '%kernel.project_dir%/src/ValueObject',
        ],
    ],
]);

Now you can use the implementing classes themselves directly in your entity like the following:

<?php

declare(strict_types=1);

namespace App\Entity;

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

#[ORM\Entity(repositoryClass: UserRepository::class)]
#[ORM\Table(name: '`user`')]
class User
{
    ...
    
    #[ORM\Column(name: 'name', type: UserName::class)]
    public UserName $name;
    
    ...
}

There are 3 interfaces that can be used for customization how the doctrine type behaves when implementing them in you classes:

`NormalizableTypeWithSQLDeclaration`

Adds a custom SQL declaration

`StringNormalizableTypeAsTypeText`

Uses type TEXT instead of the default VARCHAR(255) for strings.

`StringNormalizableTypeWithMaxLength`

Defines the max length for strings. For example: VARCHAR(50).

Custom doctrine types

If you do have custom doctrine types, you can also add them to the second configuration option for them to be registered automatically. They just need to contain the public static function getTypeName(): string method.

<?php

declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\App;

return App::config([
    'self_aware_normalizers' => [
        'doctrine_type_directories' => [
            '%kernel.project_dir%/src/Doctrine',
        ],
    ],
]);

As an added bonus, this makes sure, that the structure is always the same no matter if you're using Doctrine to read from the data or a normalizer.

digital-craftsman / self-aware-normalizers

Maintainers

Details