thecodingmachine/fluid-hydrator

A fluid builder for MetaHydrator class

FluidHydrator

This package is based on thecodingmachine/metahydrator, and aims to ease instantiation code (ie when not using dependency injection). In order to do so, it follows fluent design pattern., _(*1)

How to use

As you have probably deduced by now, the main class of this package is FluidHydrator. It implements interface Hydrator (refer to mouf/tdbm-hydrator for more details)., _(*2)

$hydrator = new FluidHydrator;

Primitive types

Use method field to declare a primitive field. Then, declare its type using int(), bool(), string(), etc., _(*3)

$hydrator->field('foo')->int();

To declare an unstructured array field (typically some decoded JSON), use the simpleArray function., _(*4)

$hydrator->field('foo')->simpleArray();

As we are these can be chained as following:, _(*5)

$hydrator
    ->field('foo')->string()->then()
    ->field('bar')->int() // Note that call o method then() is optional!
    ->field('baz')->float()
;

A type method leads to a state where you may add options to the field, mostly validators., _(*6)

$hydrator
    ->field('foo')->string()->required()->maxLength(55)
;

Array

Option array() allows to change the current type from T to array, where current validators are used for validating each entry. These can be used multiple times., _(*7)

$hydrator
    // 'foo' must be an array of non-empty arrays containing non-empty strings of length inferior to 55
    ->field('foo')->string()->required()->maxLength(55)->array()->required()->array()
;

Object types

You may also use a non-primitive type (ie a class) for a field(). Method object() then needs you to specify the hydrator used to parse the sub-data. You may pass an existant hydrator using method hydrator(), _(*8)

$hydrator
    ->field('garply')->object(Garply::class)->hydrator($garplyHydrator)
;

or even use default hydrator (being TDBMHydrator), if you do not wish to check the data sanity, _(*9)

$hydrator
    ->field('garply')->object(Garply::class)->hydrator()
;

If you want to declare the sub-hydrator on the fly, you can: declare it between a begin() and a end(), _(*10)

$hydrator
    ->field('garply')->object(Garply::class)
    ->begin()
        ->field('qux')->string()
        ->field('quux')->bool()
    ->end()
;

Note that after end() or hydrator(), you are in the same state as when typing a primitive field. Therefore, you can add validators, and even switch from T to T[] with array()!, _(*11)

Sub-Object

In some cases, you will want to access sub-objects from the top-level value being hydrated. This way, the existing value will not be replaced, but directly hydrated, respecting references and allowing partial edition., _(*12)

The field type you're looking for here is subobject(); the writing is substantially similar to object(), except for the option array() that you should not used, since it's not (yet) supported., _(*13)

$hydrator
    ->field('garply')->subobject(Garply::class)
    ->begin()
        ->field('qux')->string()
        ->field('quux')->bool()
    ->end()->required()
;