stratadox/hydrator

Hydrator

, _(*1)

, _(*2)

Lightweight hydrators, usable for various hydration purposes. Hydrate away!, _(*3)

Installation

Install with composer:, _(*4)

composer require stratadox/hydrator, _(*5)

What is this?

The Hydrator package exists in the context of object deserialization. It is useful when loading objects from a data source., _(*6)

To hydrate an object, means to assign values to its properties., _(*7)

A Hydrator populates the fields of other objects., _(*8)

Hydration generally works in tandem with Instantiation; the process of creating empty objects., _(*9)

How to use this?

Basic Objects

The most basic usage looks like this:, _(*10)

<?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., _(*11)

When that's not the case, for instance when some properties are private to the parent, a reflective hydrator is available:, _(*12)

<?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:, _(*13)

<?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., _(*14)

What else can it do?

The hydrators can be decorated to extend their capabilities., _(*15)

Mapping

To transform the input data with hydration mapping, the Mapping decorator can be used:, _(*16)

<?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., _(*17)

To observe the hydration process right before hydration begins, use:, _(*18)

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:, _(*19)

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., _(*20)