Download the PHP package patchlevel/hydrator without Composer

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

Usage

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

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

Extract Data

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

Hydrate Object

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.

[!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.

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.

[!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.

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

[!NOTE] You can read about how the format is structured in the php docs.

DateTimeZone

To normalize a DateTimeZone one can use the DateTimeZoneNormalizer.

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.

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.

[!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.

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.

[!WARNING] The important thing is that the result of Normalize is serializable!

Now we can also use the normalizer directly.

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.

Then set the attribute on the value object.

After that the DTO can then look like this.

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.

The whole thing looks like this

[!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.

Hooks

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

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.

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:

[!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.

[!WARNING] A subject ID can not be a personal data.

Configure Cryptography

Here we show you how to configure the cryptography.

Cipher Key Store

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

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.