fastnorth/property-mapper

Transforms data structures

Property Mapper

, _(*1)

A common programming task deals with transforming data structures into one another, for instance for instance processing data from an API, or a database, into objects for internal usage. This library helps with creating mappers that can be:, _(*2)

• Reversed
• Written in isolation
• Composed
• Re-used
• Tested

Usage

Mapping operations are two-fold, first you define a Map, that defines which properties map to which, after which you can use the Mapper to apply it to two entities. This library uses Symfony's PropertyAccess component internally to read and write from the given entities, so they can be both objects and arrays. The property notation follows PropertyAccess' notation., _(*3)

Creating A Map

Creating a map is simply a matter of specifying all the properties on both sides of the map:, _(*4)

<?php

use FastNorth\PropertyMapper\Map;

$map = new Map;
$map
    ->map('someProperty', 'toAnotherProperty');
    ->map('yetAnotherProperty', 'toSomethingElse');

Applying a map

Applying a map can be done by creating a Mapper, and calling process():, _(*5)

<?php

use FastNorth\PropertyMapper\Map;

// $map = ...;

$objectOne = new ClassOne;
$objectTwo = new ClassTwo;

$mapper = new Mapper;

// Applies the map, taking properties from $objectOne and applying them to $objectTwo
$mapper->process($objectOne, $objectTwo, $map);

The map can also be applied in reverse, using reverse():, _(*6)

<?php

// Applies the map in reverse, taking properties from $objectTwo and applying them to $objectOne
$mapper->reverse($objectOne, $objectTwo, $map);

Transforming Values

Part of the mapping operations is taking a value from one side of the operation, applying a transforming operation to it, then applying it to the other. For instance, date/time might be stored as a string or integer timestamp on one end, but a PHP DateTime object on the other. FastNorth PropertyMapper supports this with the concept of "Transformers"., _(*7)

Transformers are bi-directional, meaning they can process data in both directions, allowing the mapper to process maps in reverse()., _(*8)

Adding Transformers To a Map

Any transformer (implementing FastNorth\PropertyMapper\Transformer\TransformerInterface) can be passed as a third parameter to map():, _(*9)

<?php

use FastNorth\PropertyMapper\Map;
use FastNorth\PropertyMapper\Transformer\Datetime\StringToDateTime;

$map = new Map;
$map->map('aStringDateProperty', 'aDateTimeProperty', new DateTimeTransformer('Y-m-d'));