README

Hydrator

With this library you can hydrate objects from array into objects and back again with a focus on data processing from and into a database. It has now been outsourced by the event-sourcing library as a separate library.

Installation

composer require patchlevel/hydrator

Usage

To use the hydrator you just have to create an instance of it.

use Patchlevel\Hydrator\MetadataHydrator;

$hydrator = new MetadataHydrator();

After that you can hydrate any classes or objects. Also final, readonly classes with property promotion.

final readonly class ProfileCreated 
{
    public function __construct(
        public string $id,
        public string $name
    ) {
    }
}

Extract Data

To convert objects into serializable arrays, you can use the extract method:

$event = new ProfileCreated('1', 'patchlevel');

$data = $hydrator->extract($event);

[
  'id' => '1',
  'name' => 'patchlevel'
]

Hydrate Object

$event = $hydrator->hydrate(
    ProfileCreated::class,
    [
        'id' => '1',
        'name' => 'patchlevel'
    ]
);

$oldEvent == $event // true

Normalizer

For more complex structures, i.e. non-scalar data types, we use normalizers. We have some built-in normalizers for standard structures such as objects, enums, datetime etc. You can find the full list below.

The normalizers can be set on each property by using the specific attribute. For example, #[DateTimeImmutableNormalizer]. This tells the Hydrator to normalize or denormalize this property.

Fortunately, we don't have to do this everywhere. The library tries to independently recognize which normalizers are needed based on the data type. For example, if you specify DateTimeImmutable Type, the DateTimeImmutableNormalizer is automatically added. You can of course override this if you want. This makes sense, for example, if you want to adjust the format of the normalized string. You can do this by passing parameters to the normalizer.

Array

If you have a list of objects that you want to normalize, then you must normalize each object individually. That's what the ArrayNormalizer does for you. In order to use the ArrayNormaliser, you still have to specify which normaliser should be applied to the individual objects. Internally, it basically does an array_map and then runs the specified normalizer on each element.

use Patchlevel\Hydrator\Normalizer\ArrayNormalizer;
use Patchlevel\Hydrator\Normalizer\DateTimeImmutableNormalizer;

final class DTO 
{
    #[ArrayNormalizer(new DateTimeImmutableNormalizer())]
    public array $dates;
}

Note

The keys from the arrays are taken over here.

DateTimeImmutable

With the DateTimeImmutable Normalizer, as the name suggests, you can convert DateTimeImmutable objects to a String and back again.

use Patchlevel\Hydrator\Normalizer\DateTimeImmutableNormalizer;

final class DTO 
{
    #[DateTimeImmutableNormalizer]
    public DateTimeImmutable $date;
}

You can also define the format. Either describe it yourself as a string or use one of the existing constants. The default is DateTimeImmutable::ATOM.

use Patchlevel\Hydrator\Normalizer\DateTimeImmutableNormalizer;

final class DTO 
{
    #[DateTimeImmutableNormalizer(format: DateTimeImmutable::RFC3339_EXTENDED)]
    public DateTimeImmutable $date;
}

Note

You can read about how the format is structured in the php docs.

DateTime

The DateTime Normalizer works exactly like the DateTimeNormalizer. Only for DateTime objects.

use Patchlevel\Hydrator\Normalizer\DateTimeNormalizer;

final class DTO 
{
    #[DateTimeNormalizer]
    public DateTime $date;
}

You can also specify the format here. The default is DateTime::ATOM.

use Patchlevel\Hydrator\Normalizer\DateTimeNormalizer;

final class DTO 
{
    #[DateTimeNormalizer(format: DateTime::RFC3339_EXTENDED)]
    public DateTime $date;
}

Note

You can read about how the format is structured in the php docs.

DateTimeZone

To normalize a DateTimeZone one can use the DateTimeZoneNormalizer.

use Patchlevel\Hydrator\Normalizer\DateTimeZoneNormalizer;

final class DTO
{
    #[DateTimeZoneNormalizer]
    public DateTimeZone $timeZone;
}

Enum

Backed enums can also be normalized. For this, the enum FQCN must also be pass so that the EnumNormalizer knows which enum it is.

use Patchlevel\Hydrator\Normalizer\EnumNormalizer;

final class DTO
{
    #[EnumNormalizer]
    public Status $status;
}

Object

If you have a complex object that you want to normalize, you can use the ObjectNormalizer. This use the hydrator internally to normalize the object.

use Patchlevel\Hydrator\Normalizer\ObjectNormalizer;

final class DTO
{
    #[ObjectNormalizer]
    public AnohterDto $anotherDto;
    
    #[ObjectNormalizer(AnohterDto::class)]
    public object $object;
}

final class AnotherDto
{
    #[EnumNormalizer]
    public Status $status;
}

Warning

Circular references are not supported and will result in an exception.

Custom Normalizer

Since we only offer normalizers for PHP native things, you have to write your own normalizers for your own structures, such as value objects.

In our example we have built a value object that should hold a name.

final class Name
{
    private string $value;
    
    public function __construct(string $value) 
    {
        if (strlen($value) < 3) {
            throw new NameIsToShortException($value);
        }
        
        $this->value = $value;
    }
    
    public function toString(): string 
    {
        return $this->value;
    }
}

For this we now need a custom normalizer. This normalizer must implement the Normalizer interface. You also need to implement a normalize and denormalize method. Finally, you have to allow the normalizer to be used as an attribute.

use Patchlevel\Hydrator\Normalizer\Normalizer;
use Patchlevel\Hydrator\Normalizer\InvalidArgument;

#[Attribute(Attribute::TARGET_PROPERTY)]
class NameNormalizer implements Normalizer
{
    public function normalize(mixed $value): string
    {
        if (!$value instanceof Name) {
            throw InvalidArgument::withWrongType(Name::class, $value);
        }

        return $value->toString();
    }

    public function denormalize(mixed $value): ?Name
    {
        if ($value === null) {
            return null;
        }

        if (!is_string($value)) {
            throw InvalidArgument::withWrongType('string', $value);
        }

        return new Name($value);
    }
}

Warning

The important thing is that the result of Normalize is serializable!

Now we can also use the normalizer directly.

final class DTO
{
    #[NameNormalizer]
    public Name $name
}

Define normalizer on class level

You can also set the attribute on the value object on class level. For that the normalizer needs to allow to be set on class level.

use Patchlevel\Hydrator\Normalizer\Normalizer;
use Patchlevel\Hydrator\Normalizer\InvalidArgument;

#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_CLASS)]
class NameNormalizer implements Normalizer
{
    // ... same as before
}

Then set the attribute on the value object.

#[NameNormalizer]
final class Name
{
    // ... same as before
}

After that the DTO can then look like this.

final class DTO
{
    public Name $name
}

Normalized Name

By default, the property name is used to name the field in the normalized result. This can be customized with the NormalizedName attribute.

use Patchlevel\Hydrator\Attribute\NormalizedName;

final class DTO
{
    #[NormalizedName('profile_name')]
    public string $name
}

The whole thing looks like this

[
  'profile_name' => 'David'
]

Tip

You can also rename properties to events without having a backwards compatibility break by keeping the serialized name.

Ignore

Sometimes it is necessary to exclude properties. You can do that with the Ignore attribute. The property is ignored both when extracting and when hydrating.

use Patchlevel\Hydrator\Attribute\Ignore;

readonly class ProfileCreated 
{
    public function __construct(
        public string $id,
        public string $name,
        #[Ignore]
        public string $ignoreMe,
    ) {
    }
}

Hooks

Sometimes you need to do something before extract or after hydrate process. For this we have the PreExtract and PostHydrate attributes.

use Patchlevel\Hydrator\Attribute\PostHydrate;
use Patchlevel\Hydrator\Attribute\PreExtract;

readonly class Dto 
{    
    #[PostHydrate]
    private function postHydrate(): void
    {
        // do something
    }
    
    #[PreExtract]
    private function preExtract(): void
    {
        // do something
    }
}

Cryptography

The library also offers the possibility to encrypt and decrypt personal data.

PersonalData

First of all, we have to mark the fields that contain personal data. For our example, we use events, but you can do the same with aggregates.

use Patchlevel\Hydrator\Attribute\PersonalData;

final class DTO 
{
    #[PersonalData]
    public readonly string|null $email;
}

If the information could not be decrypted, then a fallback value is inserted. The default fallback value is null. You can change this by setting the fallback parameter. In this case unknown is added:

use Patchlevel\Hydrator\Attribute\PersonalData;

final class DTO
{
    public function __construct(
        #[PersonalData(fallback: 'unknown')]
        public readonly string $email,
    ) {
    }
}

[!DANGER] You have to deal with this case in your business logic such as aggregates and subscriptions.

Warning

You need to define a subject ID to use the personal data attribute.

DataSubjectId

In order for the correct key to be used, a subject ID must be defined. Without Subject Id, no personal data can be encrypted or decrypted.

use Patchlevel\Hydrator\Attribute\DataSubjectId;
use Patchlevel\Hydrator\Attribute\PersonalData;

final class EmailChanged
{
    public function __construct(
        #[DataSubjectId]
        public readonly string $personId,
        #[PersonalData(fallback: 'unknown')]
        public readonly string|null $email,
    ) {
    }
}

Warning

A subject ID can not be a personal data.

Configure Cryptography

Here we show you how to configure the cryptography.

use Patchlevel\Hydrator\Cryptography\PersonalDataPayloadCryptographer;
use Patchlevel\Hydrator\Cryptography\Store\CipherKeyStore;
use Patchlevel\Hydrator\Metadata\Event\EventMetadataFactory;
use Patchlevel\Hydrator\MetadataHydrator;

$cipherKeyStore = new InMemoryCipherKeyStore();
$cryptographer = PersonalDataPayloadCryptographer::createWithOpenssl($cipherKeyStore);
$hydrator = new MetadataHydrator(cryptographer: $cryptographer);

Cipher Key Store

The keys must be stored somewhere. For testing purposes, we offer an in-memory implementation.

use Patchlevel\Hydrator\Cryptography\Cipher\CipherKey;
use Patchlevel\Hydrator\Cryptography\Store\InMemoryCipherKeyStore;

$cipherKeyStore = new InMemoryCipherKeyStore();

/** @var CipherKey $cipherKey */
$cipherKeyStore->store('foo-id', $cipherKey);
$cipherKey = $cipherKeyStore->get('foo-id');
$cipherKeyStore->remove('foo-id');

Because we don't know where you want to store the keys, we don't offer any other implementations. You should use a database or a key store for this. To do this, you have to implement the CipherKeyStore interface.

Remove personal data

To remove personal data, you need only remove the key from the store.

$cipherKeyStore->remove('foo-id');