Download the PHP package patchlevel/hydrator without Composer

Hydrator

This library enables seamless hydration of objects to arrays—and back again. It’s optimized for both developer experience (DX) and performance.

The library is a core component of patchlevel/event-sourcing, where it powers the storage and retrieval of thousands of objects.

Hydration is handled through normalizers, especially for complex data types. The system can automatically determine the appropriate normalizer based on the data type and annotations.

In most cases, no manual configuration is needed. And if customization is required, it can be done easily using attributes.

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. These objects or classes can have complex structures in the form of value objects, DTOs or collections. Or all nested together. Here's an example:

Extract Data

To convert objects into serializable arrays, you can use the extract method of the hydrator.

The result looks like this:

We could now convert the whole thing into JSON using json_encode.

Hydrate Object

The process can also be reversed. Hydrate an array back into an object. To do this, we need to specify the class that should be created and the data that should then be written into it.

[!WARNING] It is important to know that the constructor is not called!

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, arrays, enums, datetime etc. You can find the full list below.

The library attempts to independently determine which normalizers should be used. For this purpose, normalizers of this order are determined:

1) Does the class property have a normalizer as an attribute? Use this. 2) The data type of the property is determined. 1) If it is an array shape, use the ArrayShapeNormalizer (recursive). 2) If it is a collection, use the ArrayNormalizer (recursive). 3) If it is an object, then look for a normalizer as attribute on the class or interfaces and use this. 4) If it is an object, then guess the normalizer based on the object. Fallback to the object normalizer.

The normalizer is only determined once because it is cached in the metadata. Below you will find the list of all normalizers and how to set them manually or explicitly.

Array

If you have a collection (array, iterable, list) with a data type that needs to be normalized, you can use the ArrayNormalizer and pass it the required normalizer.

[!NOTE] The keys from the arrays are taken over here.

ArrayShape

If you have an array with a specific shape, you can use the ArrayShapeNormalizer.

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.

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. Finally, you have to allow the normalizer to be used as an attribute, best to allow it for properties as well as classes.

Now we can also use the normalizer directly.

Define normalizer on class level

Instead of specifying the normalizer on each property, you can also set the normalizer on the class or on an interface.

Guess normalizer

It's also possible to write your own guesser that finds the correct normalizer based on the object. This is useful if, for example, setting the normalizer on the class or interface isn't possible.

To use this Guesser, you must specify it when creating the Hydrator:

[!NOTE] The guessers are queried in order, and the first match is returned. Finally, our built-in guesser is executed.

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.

Lazy

Since PHP 8.4, it's been possible to lazy-hydrate objects. That is, the actual hydration process occurs when the object is accessed. You can define for each class whether you want it to be lazy by using the Lazy attribute.

[!NOTE] If you are using a PHP version older than 8.4, the attribute will be ignored.

Hooks

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

Events

Another way to intervene in the extract and hydrate process is through events. There are two events: PostExtract and PreHydrate. For this functionality we use the symfony/event-dispatcher.

Cryptography

The library also offers the possibility to encrypt and decrypt personal data. For this purpose, a key is created for each subject ID, which is used to encrypt the personal data.

DataSubjectId

First we need to define what the subject id is.

[!WARNING] The DataSubjectId must be a string. You can use a normalizer to convert it to a string. The Subject ID cannot be personal data.

PersonalData

Next, we need to specify which fields we want to encrypt.

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:

You can also use a callable as a fallback.

[!TIP] Cryptography is very expensive in terms of performance, you can combine it with lazy to improve performance and only decrypt when you actually access the object.

Configure Cryptography

Here we show you how to configure the cryptography.

[!WARNING] We recommend to use the useEncryptedFieldName option to recognize encrypted fields. This allows data to be encrypted later without big troubles.

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.