feat: add map_arrays_through config to default array inputs to collections

Author: d8vjork

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Mapper registry**: custom mappers are now registered on the `MapperRegistry` container singleton with an explicit priority (`register(MyMapper::class, priority: 100)`), and higher-priority mappers win over built-ins for the same input
 - `MappingResolved` event dispatched on every mapping resolution, carrying the winning mapper class and the mapping context — replaces the previous debug logging
 - Mapping context now carries the target property, a dot-notation `path` (e.g. `tags.2`) for nested mappings, and the set of provided input keys
+- `map_arrays_through` config option: set it to `Collection::class` to get collections instead of plain arrays when mapping array input without an explicit `->through()`; inline `->through()` always takes precedence
 
 ### Changed
 

config/data-mapper.php

@@ -9,6 +9,14 @@
      */
     'normalise_properties' => true,
 
+    /**
+     * Default wrapping for array inputs when no ->through() is given.
+     *
+     * 'array' returns plain PHP arrays, \Illuminate\Support\Collection::class
+     * returns collections. Overridable per-mapping with ->through().
+     */
+    'map_arrays_through' => 'array',
+
     /**
      * Types generator config, only used as defaults when no options
      * are passed to the command.

src/Mapper.php

@@ -105,7 +105,9 @@ public function to(?string $output = null)
         $output ??= $this->dataClass;
 
         if (! $this->throughClass && (is_array($this->data) || $this->data instanceof Collection)) {
-            $this->throughClass = is_array($this->data) ? 'array' : Collection::class;
+            $this->throughClass = is_array($this->data)
+                ? (app('config')->get('data-mapper.map_arrays_through') ?? 'array')
+                : Collection::class;
         }
 
         $mappingValue = new MappingValue(

tests/MapperTest.php

@@ -52,6 +52,32 @@ public function test_map_array_of_numeric_ids_to_model_results_in_array_of_model
         $this->assertEquals($users->last()->email, $result[1]->email);
     }
 
+    public function test_map_array_configured_through_collection_results_in_collection_of_model_instances()
+    {
+        $this->app['config']->set('data-mapper.map_arrays_through', Collection::class);
+
+        $users = UserFactory::new()->count(2)->create();
+
+        $result = map([1, 2])->to(User::class);
+
+        $this->assertTrue(get_class($result) === Collection::class);
+        $this->assertEquals($users->first()->email, $result->first()->email);
+        $this->assertEquals($users->last()->email, $result->last()->email);
+    }
+
+    public function test_map_array_through_array_overrides_configured_collection_default()
+    {
+        $this->app['config']->set('data-mapper.map_arrays_through', Collection::class);
+
+        $users = UserFactory::new()->count(2)->create();
+
+        $result = map([1, 2])->through('array')->to(User::class);
+
+        $this->assertIsArray($result);
+        $this->assertEquals($users->first()->email, $result[0]->email);
+        $this->assertEquals($users->last()->email, $result[1]->email);
+    }
+
     public function test_map_multiple_numeric_ids_to_model_through_base_collection_results_in_base_collection_of_model_instances()
     {
         $users = UserFactory::new()->count(2)->create();