patchlevel / hydrator
Hydrator
Installs: 80 988
Dependents: 1
Suggesters: 0
Security: 0
Stars: 4
Watchers: 3
Forks: 0
Open Issues: 6
Requires
- php: ~8.1.0 || ~8.2.0 || ~8.3.0
- ext-openssl: *
Requires (Dev)
- cspray/phinal: ^2.0.0
- infection/infection: ^0.27.8
- patchlevel/coding-standard: ^1.3.0
- phpbench/phpbench: ^1.2.15
- phpspec/prophecy-phpunit: ^2.1.0
- phpstan/phpstan: ^1.10.49
- phpunit/phpunit: ^10.5.2
- psalm/plugin-phpunit: ^0.19.0
- psr/cache: ^2.0.0|^3.0.0
- psr/simple-cache: ^2.0.0|^3.0.0
- roave/infection-static-analysis-plugin: ^1.34.0
- symfony/var-dumper: ^5.4.29|^6.4.0|^7.0.0
- vimeo/psalm: ^5.17.0
- 1.6.x-dev
- 1.5.x-dev
- 1.5.1
- 1.5.0
- 1.4.x-dev
- 1.4.1
- 1.4.0
- 1.3.x-dev
- 1.3.2
- 1.3.1
- 1.3.0
- 1.2.x-dev
- 1.2.0
- 1.1.x-dev
- 1.1.0
- 1.0.x-dev
- 1.0.0
- 1.0.0-beta5
- 1.0.0-beta4
- 1.0.0-beta3
- 1.0.0-beta2
- 1.0.0-beta1
- dev-renovate/phpunit-phpunit-11.x
- dev-renovate/infection-infection-0.x
- dev-renovate/lock-file-maintenance
- dev-guesser
- dev-union-object-normalizer
- dev-service-normalizer
- dev-fix-readme
This package is auto-updated.
Last update: 2024-11-07 05:08:53 UTC
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
Sometimes you also need to extract or hydrate more complex objects. To do that you can use normalizer. For some the standard cases we already offer built-in normalizers.
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 }
Infer Normalizer
We also integrated a process where the normalizer gets inferred by type. This means you don't need to define the
normalizer in for the properties or on class level. Right now this is only possible for Normalizer defined by our
library. There are exceptions though, the ObjectNormalizer
and the ArrayNormalizer
.
These Normalizer can be inferred:
DateTimeImmutableNormalizer
DateTimeNormalizer
DateTimeZoneNormalizer
EnumNormalizer
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');