biig/optimus

0.2.3 2019-03-06 11:05 UTC

Requires

• php: ^5.6|>=7.0.8
• ext-json: *
• symfony/property-access: ^3.4| ^4.0

Requires (Dev)

• phpunit/phpunit: ^5.7

Suggests

• symfony/yaml: To parse your YAML files

MIT

• BiiG

README

The goal of the library is to map two arrays (in and out) with an YAML file config.

• This library respects SemVer.

Install

You can install this library using composer with the following command:

composer require biig/optimus

Usage

To use this library, you have to create a transformer which needs to extends the AbstractMappingTransformer class.

This Transformer will read mapping and apply it to input data.

Basic example

Transformer

You first have to create your Transformer and implement transform method.
Here we use symfony/yaml ^3.4 to parse a YAML file.

<?php
 
namespace Transformer;
 
use Biig\Optimus\AbstractMappingTransformer;
use Symfony\Component\Yaml\Yaml;
 
class MyTransformer extends AbstractMappingTransformer
{
    /**
     * {@inheritdoc}
     */
    protected function transform(array $inputArray)
    {
        $config = Yaml::parseFile('/mapping.yaml');
        $result = $this->transformFromMapping($config['transformer']['mapping'], $inputArray);
        // ...
        return $result;
    }
}

The $result variable now contains the new array.

Configuration

Assuming you got the PHP array $inputArray (input data)

$inputArray = [
    'user' => [
        'civility' => 'M',
        'firstname' => 'John',
        'lastname' => 'Doe',
    ],
    'title' => 'A title',
];

And considering you want to transform it to the following array (expected output)

$outputArray = [
    'title' => 'A title',
    'participants' => [
        0 => [
            'civility' => 'M',
            'name' => 'Doe',
        ],
    ],
];

You will have to implements the following YAML:

# mapping.yaml
transformer:
    mapping:
        title:
            from: 'title'
            to: 'title'
        participants_1_civility:
            from: 'user.civility'
            to: 'participants.0.civility'
        participants_1_name:
            from: 'user.lastname'
            to: 'participants.0.name'

Available mapping options

You can declare your node

• from : string, the key path of the input array
• to : string, the key path of the output array
• function : array, the php function to use to transform the data
  • name : string, the function's name
  • params : [Optional] array, the function's parameters (key paths of the input array)
• required : boolean, if the key is required
• condition : array, the conditions that specify if the key is required or not

Examples

Transform a key a to key b

from: a
to: b

Get a key b by using a function

to: b
function:
    name: getB
    params: [a]

Note: Function getB($arg1) must be declared in your related transformer You can use functions to transform the input value to the expected value. For example person civility (Mr, Mrs) to numbers (1, 2)

public function getCivility($civility)
{
    $array = [
        'Mr' => 1,
        'Mrs' => 2,
    ];
    
    return $array[$civility];
}

Make a field required

Actually, if from value don't exist in your input array, the to field don't appear in the output array.
If you want this field required, you can add required key.

from: a
to: b
required: true # Default to false

Use a default value

Actually, if from value doesn't exist in your input array, the to field doesn't appear in the output array.
If you want this field to get a default value, you can add default key.

from: a
to: b
default: 1 # If key "a" don't exist, "b" value will be "1"

from: a
to: b
default:
    function:
        name: getB # You can also use a function to define default value

Add a condition

If you want to transform a field A only if a field B exists.

from: a
to: foo
condition:
    exists: b

You can put multiple fields in your condition :

from: a
to: foo
condition:
    exists:
        - b
        - c

Get all errors mapping at a time

If you want to return all errors at a time you can set the next parameters in config

# mapping.yaml
transformer:
    parameters:
      show_all_errors: true
    mapping:
        title:
            from: 'title'
            to: 'title'
        participants_1_civility:
            from: 'user.civility'
            to: 'participants.0.civility'
        participants_1_name:
            from: 'user.lastname'
            to: 'participants.0.name'