biig / optimus
Installs: 12 138
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 8
Forks: 4
Open Issues: 1
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
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 theinput
arrayto
: string, the key path of theoutput
arrayfunction
: array, the php function to use to transform the dataname
: string, the function's nameparams
: [Optional] array, the function's parameters (key paths of theinput
array)
required
: boolean, if the key isrequired
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'