Improve tests, README

README.md

@@ -33,6 +33,136 @@ The solution provided by Doctrine doesn't work. The creation of this bundle aros
 
 ## How to use?
 
+### Add mapping to your DTOs
+
+This bundle comes with several attributes that you can use to add mapping to your DTOs:
+
+- `#[Identifier]`: Any DTO has to have at least one identifier. This identifier is used to create the DTO only once.
+- `#[InboundProperty("property_name")]`: The name of the key on the associative arrays contained by your result set. This is optional if your DTO's property names are already matching the result set.
+- `#[ReferencesArray(NestedDTO::class)]`: An array of `NestedDTO` will be created using the mapping information contained in `NestedDTO`
+- `#[ColumnArray("property_name")]` the column `property_name` of your result set will be mapped as an array of scalar properties (such as IDs).
+
+### Hydrating nested DTOs
+
+Given:
+
+- [RootDTO](tests/Examples/Valid/RootDTO.php)
+- [LeafDTO](tests/Examples/Valid/LeafDTO.php)
+
+Calling FlatMapper with the following result set:
+
+```php
+$results = [
+    ['object1_id' => 1, 'object1_name' => 'Root 1', 'object2_id' => 1, 'object2_name' => 'Leaf 1', 'object2_value' => 'Value 1'],
+    ['object1_id' => 1, 'object1_name' => 'Root 1', 'object2_id' => 2, 'object2_name' => 'Leaf 2', 'object2_value' => 'Value 2'],
+    ['object1_id' => 1, 'object1_name' => 'Root 1', 'object2_id' => 3, 'object2_name' => 'Leaf 3', 'object2_value' => 'Value 3'],
+    ['object1_id' => 2, 'object1_name' => 'Root 2', 'object2_id' => 1, 'object2_name' => 'Leaf 1', 'object2_value' => 'Value 1'],
+    ['object1_id' => 2, 'object1_name' => 'Root 2', 'object2_id' => 4, 'object2_name' => 'Leaf 4', 'object2_value' => 'Value 4'],
+];
+
+$flatMapper->map(RootDTO::class, $results);
+```
+
+Will output:
+
+```php
+Array
+(
+    [1] => RootDTO Object
+        (
+            [id] => 1
+            [name] => Root 1
+            [leafs] => Array
+                (
+                    [1] => LeafDTO Object
+                        (
+                            [id] => 1
+                            [name] => Leaf 1
+                            [value] => Value 1
+                        )
+
+                    [2] => LeafDTO Object
+                        (
+                            [id] => 2
+                            [name] => Leaf 2
+                            [value] => Value 2
+                        )
+
+                    [3] => LeafDTO Object
+                        (
+                            [id] => 3
+                            [name] => Leaf 3
+                            [value] => Value 3
+                        )
+                )
+        )
+    [2] => RootDTO Object
+        (
+            [id] => 2
+            [name] => Root 2
+            [leafs] => Array
+                (
+                    [1] => LeafDTO Object
+                        (
+                            [id] => 1
+                            [name] => Leaf 1
+                            [value] => Value 1
+                        )
+                    [4] => LeafDTO Object
+                        (
+                            [id] => 4
+                            [name] => Leaf 4
+                            [value] => Value 4
+                        )
+                )
+        )
+)
+```
+
+### Hydrating Column Arrays
+
+Given [ColumnArrayDTO](tests/Examples/Valid/ColumnArrayDTO.php)
+
+Calling FlatMapper with the following result set:
+```php
+$results = [
+    ['object1_id' => 1, 'object1_name' => 'Root 1', 'object2_id' => 1],
+    ['object1_id' => 1, 'object1_name' => 'Root 1', 'object2_id' => 2],
+    ['object1_id' => 1, 'object1_name' => 'Root 1', 'object2_id' => 3],
+    ['object1_id' => 2, 'object1_name' => 'Root 2', 'object2_id' => 1],
+    ['object1_id' => 2, 'object1_name' => 'Root 2', 'object2_id' => 4],
+];
+```
+
+Will output:
+
+```php
+Array
+(
+    [1] => ColumnArrayDTO Object
+        (
+            [id] => 1
+            [name] => Root 1
+            [object2s] => Array
+                (
+                    [0] => 1
+                    [1] => 2
+                    [2] => 3
+                )
+        )
+    [2] => ColumnArrayDTO Object
+        (
+            [id] => 2
+            [name] => Root 2
+            [object2s] => Array
+                (
+                    [0] => 1
+                    [1] => 4
+                )
+        )
+)
+```
+
 ### Working with Doctrine Queries
 
 Given the following DTO class:

tests/FlatMapperTest.php

@@ -7,6 +7,7 @@
 use PHPUnit\Framework\TestCase;
 use Pixelshaped\FlatMapperBundle\FlatMapper;
 use Pixelshaped\FlatMapperBundle\Tests\Examples\Valid\ColumnArrayDTO;
+use Pixelshaped\FlatMapperBundle\Tests\Examples\Valid\LeafDTO;
 use Pixelshaped\FlatMapperBundle\Tests\Examples\Valid\RootDTO as ValidRootDTO;
 use Pixelshaped\FlatMapperBundle\Tests\Examples\Invalid\RootDTO as InvalidRootDTO;
 use RuntimeException;
@@ -31,7 +32,7 @@ public function testCreateMappingWithInvalidDTOsAsserts(): void
         $mapper->createMapping(InvalidRootDTO::class);
     }
 
-    public function testMapValidObject(): void
+    public function testMapValidNestedDTOs(): void
     {
         $results = [
             ['object1_id' => 1, 'object1_name' => 'Root 1', 'object2_id' => 1, 'object2_name' => 'Leaf 1', 'object2_value' => 'Value 1'],
@@ -41,10 +42,46 @@ public function testMapValidObject(): void
             ['object1_id' => 2, 'object1_name' => 'Root 2', 'object2_id' => 4, 'object2_name' => 'Leaf 4', 'object2_value' => 'Value 4'],
         ];
 
-        $mappedResults = ((new FlatMapper())->map(ValidRootDTO::class, $results));
+        $flatMapperResults = ((new FlatMapper())->map(ValidRootDTO::class, $results));
 
-        $this->assertSame(count($mappedResults), 2);
+        $leafDto1 = new LeafDTO(1, "Leaf 1", "Value 1");
+        $leafDto2 = new LeafDTO(2, "Leaf 2", "Value 2");
+        $leafDto3 = new LeafDTO(3, "Leaf 3", "Value 3");
+        $leafDto4 = new LeafDTO(4, "Leaf 4", "Value 4");
 
+        $rootDto1 = new ValidRootDTO(1, "Root 1", [
+            1 => $leafDto1, 2 => $leafDto2, 3 => $leafDto3
+        ]);
+        $rootDto2 = new ValidRootDTO(2, "Root 2", [
+            1 => $leafDto1, 4 => $leafDto4
+        ]);
+        $handmadeResult = [1 => $rootDto1, 2 => $rootDto2];
 
+        $this->assertSame(
+            var_export($flatMapperResults, true),
+            var_export($handmadeResult, true)
+        );
+    }
+
+    public function testMapValidColumnArrayDTO(): void
+    {
+        $results = [
+            ['object1_id' => 1, 'object1_name' => 'Root 1', 'object2_id' => 1],
+            ['object1_id' => 1, 'object1_name' => 'Root 1', 'object2_id' => 2],
+            ['object1_id' => 1, 'object1_name' => 'Root 1', 'object2_id' => 3],
+            ['object1_id' => 2, 'object1_name' => 'Root 2', 'object2_id' => 1],
+            ['object1_id' => 2, 'object1_name' => 'Root 2', 'object2_id' => 4],
+        ];
+
+        $flatMapperResults = ((new FlatMapper())->map(ColumnArrayDTO::class, $results));
+
+        $rootDto1 = new ColumnArrayDTO(1, "Root 1", [1, 2, 3]);
+        $rootDto2 = new ColumnArrayDTO(2, "Root 2", [1, 4]);
+        $handmadeResult = [1 => $rootDto1, 2 => $rootDto2];
+
+        $this->assertSame(
+            var_export($flatMapperResults, true),
+            var_export($handmadeResult, true)
+        );
     }
 }