stratadox / hydrator
Requires
- php: >=7.2
- stratadox/hydration-mapping-contracts: ^0.4
- stratadox/hydrator-contracts: ^0.8
- stratadox/instantiator: ^0.2
Requires (Dev)
- fzaninotto/faker: ^1.7
- phpstan/phpstan: ^0.12.54
- phpunit/phpunit: ^7.1
- stratadox/immutable-collection: ^1.1
Suggests
- stratadox/hydration-mapping: For mapping the hydration data.
README
Lightweight hydrators, usable for various hydration purposes. Hydrate away!
Installation
Install with composer:
composer require stratadox/hydrator
What is this?
The Hydrator
package exists in the context of object deserialization.
It is useful when loading objects from a data source.
To hydrate an object, means to assign values to its properties.
A Hydrator
populates the
fields of other objects.
Hydration generally works in tandem with Instantiation
;
the process of creating empty objects.
How to use this?
Basic Objects
The most basic usage looks like this:
<?php use Stratadox\Hydrator\ObjectHydrator; $hydrator = ObjectHydrator::default(); $thing = new Thing(); $hydrator->writeTo($thing, [ 'foo' => 'Bar.', 'property' => 'value', ]); assert($thing->foo === 'Bar.'); assert($thing->getProperty() === 'value');
The default hydrator requires the hydrated object to have access to all of its own properties.
When that's not the case, for instance when some properties are private to the
parent, a reflective
hydrator is available:
<?php use Stratadox\Hydrator\ReflectiveHydrator; $hydrator = ReflectiveHydrator::default();
Collection Objects
To hydrate collection objects, the Hydrator
package provides either a
MutableCollectionHydrator
, suitable for most collection classes:
<?php use Stratadox\Hydrator\MutableCollectionHydrator; $hydrator = MutableCollectionHydrator::default(); $collection = new SplFixedArray; $hydrator->writeTo($collection, ['foo', 'bar']); assert(2 === count($collection));
The MutableCollectionHydrator
hydrates by mutating the collection object.
Naturally, this will not work when your collections are immutable,
in which case the ImmutableCollectionHydrator
should be used instead.
What else can it do?
The hydrators can be decorated to extend their capabilities.
Mapping
To transform the input data with hydration mapping,
the Mapping
decorator can be used:
<?php use Stratadox\HydrationMapping\IntegerValue; use Stratadox\HydrationMapping\StringValue; use Stratadox\Hydrator\MappedHydrator; use Stratadox\Hydrator\ObjectHydrator; $hydrator = MappedHydrator::using( ObjectHydrator::default(), StringValue::inProperty('title'), IntegerValue::inProperty('rating'), StringValue::inPropertyWithDifferentKey('isbn', 'id') ); $book = new Book; $hydrator->writeTo($book, [ 'title' => 'This is a book.', 'rating' => 3, 'isbn' => '0000000001' ]);
Observing
The hydration process can be observed in two ways: before or after hydrating.
To observe the hydration process right before hydration begins, use:
use Stratadox\Hydrator\ObjectHydrator; use Stratadox\Hydrator\ObserveBefore; $hydrator = ObserveBefore::hydrating(ObjectHydrator::default(), new MyCustomObserver());
To observe the hydration process right after hydration is done, use:
use Stratadox\Hydrator\ObjectHydrator; use Stratadox\Hydrator\ObserveAfter; $hydrator = ObserveAfter::hydrating(ObjectHydrator::default(), new MyCustomObserver());
The observer must be a HydrationObserver
.
It will receive both the object instance and the input data.