Added key propagation to CollectionMapper.

Changed CollectionMapper to return collection keys instead of renumbering *potential BC break*.
Added InvalidRecordException thrown by CollectionMapper.

Author: Paul

src/CollectionMapper.php

@@ -13,17 +13,17 @@ class CollectionMapper extends Mapper
      *
      * @return \Generator
      *
-     * @throws \Exception
+     * @throws InvalidRecordException A record in the specified collection was not an array type.
      */
     public function mapCollection(\Iterator $collection, Mapping $mapping = null, $context = null)
     {
-        foreach ($collection as $record) {
+        foreach ($collection as $key => $record) {
             if (!is_array($record)) {
-                throw new \Exception('Record must be an array.'); // TODO: Specific exception type.
+                throw new InvalidRecordException('Record must be an array.');
             }
 
-            yield $mapping
-                ? $this->mapMapping($record, $mapping, $context)
+            yield $key => $mapping
+                ? $this->mapMapping($record, $mapping, $context, $key)
                 : $record;
         }
     }

src/InvalidRecordException.php

@@ -0,0 +1,10 @@
+<?php
+namespace ScriptFUSION\Mapper;
+
+/**
+ * The exception that is thrown when an invalid record type is specified.
+ */
+class InvalidRecordException extends \RuntimeException
+{
+    // Intentionally empty.
+}

test/Functional/KeyPropagationTest.php

@@ -1,6 +1,8 @@
 <?php
 namespace ScriptFUSIONTest\Functional;
 
+use ScriptFUSION\Mapper\AnonymousMapping;
+use ScriptFUSION\Mapper\CollectionMapper;
 use ScriptFUSION\Mapper\Mapper;
 use ScriptFUSION\Mapper\Strategy\Collection;
 use ScriptFUSION\Mapper\Strategy\Context;
@@ -49,4 +51,17 @@ public function testStrategyPropagation()
 
         self::assertSame(['bar' => 'bar'], $mapped);
     }
+
+    /**
+     * Tests that keys are forwarded by CollectionMapper.
+     */
+    public function testCollectionMapperPropagation()
+    {
+        $mapped = (new CollectionMapper)->mapCollection(
+            new \ArrayIterator(['foo' => ['bar']]),
+            new AnonymousMapping([new CopyKey])
+        );
+
+        self::assertSame(['foo' => ['foo']], iterator_to_array($mapped));
+    }
 }

test/Integration/Mapper/CollectionMapperTest.php

@@ -3,6 +3,7 @@
 
 use ScriptFUSION\Mapper\AnonymousMapping;
 use ScriptFUSION\Mapper\CollectionMapper;
+use ScriptFUSION\Mapper\InvalidRecordException;
 
 final class CollectionMapperTest extends \PHPUnit_Framework_TestCase
 {
@@ -14,6 +15,16 @@ protected function setUp()
         $this->mapper = new CollectionMapper;
     }
 
+    /**
+     * Tests that when an invalid collection is specified an exception is thrown.
+     */
+    public function testMapInvalidCollection()
+    {
+        $this->setExpectedException(InvalidRecordException::class);
+
+        $this->mapper->mapCollection(new \ArrayIterator(['foo']))->valid();
+    }
+
     /**
      * Tests that when there is nothing to map an invalid Generator is returned.
      */
@@ -53,4 +64,17 @@ public function testMapCollection()
 
         self::assertSame([$record, $record], iterator_to_array($mapped));
     }
+
+    /**
+     * Tests that the keys of a mapped collection are preserved.
+     */
+    public function testCollectionKeysPreserved()
+    {
+        $mapped = $this->mapper->mapCollection(
+            new \ArrayIterator($input = ['foo' => ['bar']]),
+            new AnonymousMapping(['baz'])
+        );
+
+        self::assertSame(['foo' => ['baz']], iterator_to_array($mapped));
+    }
 }