From 4edc7a4a3181b8f88423e9061a83d75e1cffbb00 Mon Sep 17 00:00:00 2001 From: Donovan Bourlard Date: Fri, 2 Mar 2018 12:49:40 +0100 Subject: [PATCH] Update namespaces + README --- LICENSE | 21 +++ README.md | 195 ++++++++++++++++------- composer.json | 11 +- src/AbstractMappingTransformer.php | 2 +- tests/AbstractMappingTransformerTest.php | 4 +- 5 files changed, 164 insertions(+), 69 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..7b5e2fe --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2016-2017 Maxime Veber + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index b07c5b0..c82065d 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,39 @@ -# Array mapping +# Optimus The goal of the library is to map two arrays (in and out) with an YAML file config. -## Install +- **_This library respects [SemVer](https://semver.org/)._** + -WIP, not official lib yet +## Install +You can install this library using composer with the following command: ```bash -composer require valouleloup/array-mapping +composer require biig-io/optimus ``` + + + ## Usage -#### Yaml Mapping +To use this library, you have to create a transformer which needs to extends the `AbstractMappingTransformer` class. -```yaml -transformer: - mapping: - civilite: - from: 'demandeur.civilite' - to: 'civ' - function: - name: 'buildCivilite' - params: - - 'demandeur.civilite' - nom: - from: 'demandeur.nomUsage' - to: 'nom' - required: true - prenom: - from: 'demandeur.prenom' - to: 'prenom' - required: true - dateNaissance: - from: 'demandeur.dateNaissance' - to: 'dnat' - function: - name: 'convertDate' - params: - - 'demandeur.dateNaissance' - villeNaissance: - from: 'demandeur.naissanceVille' - to: 'villenaiss' -``` +This Transformer will read mapping and apply it to input data. -* ` from ` : string, the key's path of the ` in ` array -* ` to ` : string, the key's path of the ` out ` array -* ` function ` : array, the php function to use to transform the data - * ` name ` : string, the function's name - * ` params ` : array, the function's parameters -* ` required ` : boolean, if the key is ` required ` -* WIP ` condition ` : array, the conditions that specify if the key is required or not +## Basic example -#### Transformer +### Transformer -Your transformer needs to extends the ` MappingTransformer ` class : +You first have to create your Transformer and implement `transform` method. +Here we use `symfony/yaml ^3.4` to parse a YAML file. ```php = 3.4 - $config = Yaml::parse(file_get_contents(__DIR__ . '/mapping.yml')); - $result = $this->transformFromMapping($config['transformer']['mapping'], $dataBefore); - ... + $config = Yaml::parseFile('/mapping.yaml'); + $result = $this->transformFromMapping($config['transformer']['mapping'], $inputArray); + // ... + return $result; } - - /** - * @param $value - * - * @return string - */ - public function convertDate($value) - { - $date = new DateTime($value); +} +``` +The ` $result ` variable now contains the new array. - return $date->format('d/m/Y'); - } +### The input data + +Assuming you got the PHP array `$inputArray` +```php +$inputArray = [ + 'user' => [ + 'civility' => 'M', + 'firstname' => 'John', + 'lastname' => 'Doe', + ], + 'title' => 'A title', +]; +``` + +### YAML Mapping + +Consider you want to transform it to the following array +```php +$outputArray = [ + 'title' => 'A title', + 'participants' => [ + 0 => [ + 'civility' => 'M', + 'name' => 'Doe', + ], + ], +]; +``` + +You will have to implements the following YAML: +```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 + +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` +```yaml +from: a +to: b +``` + +#### Get a key `b` by using a function +```yaml +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) +```php +public function getCivility($civility) +{ + $array = [ + 'Mr' => 1, + 'Mrs' => 2, + ]; + + return $array[$civility]; } ``` -The ` $result ` variable now contains the new array. +#### 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. +```yaml +from: a +to: b +required: true # Default to false +``` + +#### Use a default value +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 to got a default value, you can add `default` key. +```yaml +from: a +to: b +default: 1 # If key "a" don't exist, "b" value will be "1" +``` + +```yaml +from: a +to: b +default: + function: + name: getB # You can also use a function to define default value +``` diff --git a/composer.json b/composer.json index 42f1965..748dfe7 100644 --- a/composer.json +++ b/composer.json @@ -1,5 +1,5 @@ { - "name": "valouleloup/array-mapping", + "name": "biig-io/optimus", "type": "library", "license": "MIT", "authors": [ @@ -10,19 +10,22 @@ ], "autoload": { "psr-4": { - "Valouleloup\\ArrayMapping\\": "src/" + "Biig\\Optimus\\": "src/" } }, "autoload-dev": { "psr-4": { - "Valouleloup\\ArrayMapping\\Tests\\": "tests/" + "Biig\\Optimus\\Tests\\": "tests/" } }, "require": { "php": "^5.6|>=7.0.8", - "symfony/property-access": "^3.4" + "symfony/property-access": "^3.4", }, "require-dev": { "phpunit/phpunit": "^5.7" + }, + "suggest": { + "symfony/yaml": "^3.4" } } diff --git a/src/AbstractMappingTransformer.php b/src/AbstractMappingTransformer.php index ba9f91c..12bcafb 100644 --- a/src/AbstractMappingTransformer.php +++ b/src/AbstractMappingTransformer.php @@ -1,6 +1,6 @@