docs: add documentation for mapping collections feature (#248)

fix #241

Author: joelwurtz

docs/_nav.md

@@ -7,6 +7,7 @@
 - [Mapping](mapping/index.md)
     - [MapTo and MapFrom attributes](mapping/attributes.md)
     - [Symfony Serializer](mapping/serializer.md)
+    - [Mapping Collections](mapping/map-collection.md)
     - [Ignoring properties](mapping/ignoring-properties.md)
     - [Conditional mapping](mapping/conditional-mapping.md)
     - [Groups](mapping/groups.md)

docs/index.md

@@ -26,6 +26,15 @@ $target = $automapper->map($source, Target::class);
 That's it! `AutoMapper` will find the best way to map from `$source` object to a new `Target` object. It will also
 generate a PHP class that will do the mapping for you and serve as a cache for future mapping.
 
+### Mapping Collections
+
+AutoMapper can also map collections of objects with the `mapCollection` method:
+
+```php
+$sources = [$source1, $source2, $source3];
+$targets = $automapper->mapCollection($sources, Target::class);
+```
+
 Of course there are many ways to customize the mapping, this documentation will explain all of them.
 
 ## Installation 📦

docs/mapping/map-collection.md

@@ -0,0 +1,44 @@
+# Mapping Collections
+
+When working with AutoMapper, you often need to map not just a single object, but a collection of objects. The `mapCollection()` method is designed specifically for this purpose.
+
+## Basic Usage
+
+The `mapCollection()` method allows you to transform a collection of objects from one type to another:
+
+```php
+use AutoMapper\AutoMapper;
+
+$automapper = AutoMapper::create();
+
+$sources = [
+    new Source('value1'),
+    new Source('value2'),
+    new Source('value3'),
+];
+
+$targets = $automapper->mapCollection($sources, Target::class);
+```
+
+This will return an array where each element from the source collection is mapped to a new instance of the target class.
+
+## Collection Types Support
+
+AutoMapper's `mapCollection()` supports any `iterable`
+
+The method will return an array of object that was provided as a target class:
+
+```php
+$targetsArray = $automapper->mapCollection($sourcesArray, Target::class);
+```
+
+## Using Context
+
+Just like the `map()` method, `mapCollection()` also accepts a context parameter for customizing the mapping process:
+
+```php
+$context = ['groups' => ['read']];
+$targets = $automapper->mapCollection($sources, Target::class, $context);
+```
+
+This context will be applied to each individual object mapping operation.