Update namespaces + README

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.

README.md

@@ -1,96 +1,167 @@
-# 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
 <?php
 
 namespace Transformer;
 
-use DateTime;
-use Valouleloup\ArrayMapping\AbstractMappingTransformer;
+use Biig\Optimus\AbstractMappingTransformer;
 use Symfony\Component\Yaml\Yaml;
 
 class MyTransformer extends AbstractMappingTransformer
 {
     /**
      * {@inheritdoc}
      */
-    protected function transform(array $dataBefore)
+    protected function transform(array $inputArray)
     {
-        // TODO use parseFile for SF >= 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
+```

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"
     }
 }

src/AbstractMappingTransformer.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Valouleloup\ArrayMapping;
+namespace Biig\Optimus;
 
 use Symfony\Component\PropertyAccess\PropertyAccess;
 use Symfony\Component\PropertyAccess\PropertyAccessor;

tests/AbstractMappingTransformerTest.php

@@ -1,9 +1,9 @@
 <?php
 
-namespace Valouleloup\ArrayMapping\Tests;
+namespace Biig\Optimus\Tests;
 
 use PHPUnit\Framework\TestCase;
-use Valouleloup\ArrayMapping\AbstractMappingTransformer;
+use Biig\Optimus\AbstractMappingTransformer;
 
 class AbstractMappingTransformerTest extends TestCase
 {