Added CopyKey strategy, KeyAware interface and KeyAwareTrait.

Changed Mapper to forward keys to expressions.
Changed Delegate to forward keys to mapper.
Changed Collection to forward keys.
Added unit and integration tests for CopyKey.

Author: Paul

src/KeyAware.php

@@ -0,0 +1,14 @@
+<?php
+namespace ScriptFUSION\Mapper;
+
+interface KeyAware
+{
+    /**
+     * Sets the key to the specified value.
+     *
+     * @param string|int $key Key.
+     *
+     * @return void
+     */
+    public function setKey($key);
+}

src/KeyAwareTrait.php

@@ -0,0 +1,15 @@
+<?php
+namespace ScriptFUSION\Mapper;
+
+trait KeyAwareTrait
+{
+    /**
+     * @var string|int
+     */
+    private $key;
+
+    public function setKey($key)
+    {
+        $this->key = $key;
+    }
+}

src/Mapper.php

@@ -14,23 +14,24 @@ class Mapper
      *
      * @param array $record Record.
      * @param Strategy|Mapping|array|mixed $expression Expression.
-     * @param mixed $context Context.
+     * @param mixed $context Optional. Contextual data.
+     * @param string|int|null $key Internal. Record key.
      *
      * @return mixed
      *
      * @throws InvalidExpressionException An invalid strategy or mapping object was specified.
      */
-    public function map(array $record, $expression, $context = null)
+    public function map(array $record, $expression, $context = null, $key = null)
     {
         /* Strategy. */
         if ($expression instanceof Strategy) {
-            return $this->mapStrategy($record, $expression, $context);
+            return $this->mapStrategy($record, $expression, $context, $key);
         } /* Mapping. */
         elseif ($expression instanceof Mapping) {
-            return $this->mapMapping($record, $expression, $context);
+            return $this->mapMapping($record, $expression, $context, $key);
         } /* Mapping fragment. */
         elseif (is_array($expression)) {
-            return $this->mapFragment($record, $expression, $context);
+            return $this->mapFragment($record, $expression, $context, $key);
         } /* Null or scalar values. */
         elseif (null === $expression || is_scalar($expression)) {
             return $expression;
@@ -42,15 +43,16 @@ public function map(array $record, $expression, $context = null)
     /**
      * @param array $record Record.
      * @param Mapping $mapping Mapping.
-     * @param mixed $context Contextual data.
+     * @param mixed $context Optional. Contextual data.
+     * @param string|int|null $key Internal. Record key.
      *
      * @return array Mapped record.
      *
      * @throws \Exception
      */
-    protected function mapMapping(array $record, Mapping $mapping, $context = null)
+    protected function mapMapping(array $record, Mapping $mapping, $context = null, $key = null)
     {
-        $mapped = $this->mapFragment($record, $mapping->toArray(), $context);
+        $mapped = $this->mapFragment($record, $mapping->toArray(), $context, $key);
 
         if ($mapping->isWrapped()) {
             // Unwrap.
@@ -60,12 +62,23 @@ protected function mapMapping(array $record, Mapping $mapping, $context = null)
         return $mapped;
     }
 
-    protected function mapFragment(array $record, array $fragment, $context = null)
+    /**
+     * @param array $record Record.
+     * @param array $fragment Mapping.
+     * @param null $context Optional. Contextual data.
+     * @param string|int|null $key Internal. Record key.
+     *
+     * @return array Mapped record.
+     *
+     * @throws \Exception Mapping failed for an unknown reason.
+     */
+    protected function mapFragment(array $record, array $fragment, $context = null, $key = null)
     {
         if (array_walk(
             $fragment,
-            function (&$strategy, $key, array $record) use ($context) {
-                $strategy = $this->map($record, $strategy, $context);
+            // Mapping fragment keys are not useful because they are hard-coded.
+            function (&$expression, $_, array $record) use ($context, $key) {
+                $expression = $this->map($record, $expression, $context, $key);
             },
             $record
         )) {
@@ -76,14 +89,17 @@ function (&$strategy, $key, array $record) use ($context) {
     }
 
     /**
-     * @param array $record
-     * @param Strategy $strategy
-     * @param mixed $context
+     * @param array $record Record.
+     * @param Strategy $strategy Strategy.
+     * @param mixed $context Optional. Contextual data.
+     * @param string|int|null $key Internal. Record key.
      *
      * @return mixed
      */
-    protected function mapStrategy(array $record, Strategy $strategy, $context = null)
+    protected function mapStrategy(array $record, Strategy $strategy, $context = null, $key = null)
     {
+        $strategy instanceof KeyAware && $strategy->setKey($key);
+
         $this->injectDependencies($strategy);
 
         return $strategy($record, $context);

src/Strategy/Collection.php

@@ -31,8 +31,10 @@ public function __invoke($data, $context = null)
             return null;
         }
 
-        return array_map(function ($context) use ($data) {
-            return $this->delegate($this->transformation, $data, $context);
-        }, $collection);
+        array_walk($collection, function (&$value, $key) use ($data) {
+            $value = $this->delegate($this->transformation, $data, $value, $key);
+        });
+
+        return $collection;
     }
 }

src/Strategy/CopyKey.php

@@ -0,0 +1,18 @@
+<?php
+namespace ScriptFUSION\Mapper\Strategy;
+
+use ScriptFUSION\Mapper\KeyAware;
+use ScriptFUSION\Mapper\KeyAwareTrait;
+
+/**
+ * Copies the current key.
+ */
+class CopyKey implements Strategy, KeyAware
+{
+    use KeyAwareTrait;
+
+    public function __invoke($data, $context = null)
+    {
+        return $this->key;
+    }
+}

src/Strategy/Delegate.php

@@ -24,8 +24,8 @@ public function __invoke($data, $context = null)
         return $this->delegate($this->expression, $data, $context);
     }
 
-    protected function delegate($strategy, $data, $context)
+    protected function delegate($strategy, $data, $context, $key = null)
     {
-        return $this->mapper->map($data, $strategy, $context);
+        return $this->mapper->map($data, $strategy, $context, $key);
     }
 }

test/Integration/Mapper/Strategy/CollectionTest.php

@@ -20,22 +20,26 @@ public function testCollection()
     {
         /** @var Collection $collection */
         $collection = (new Collection(
-            $this->createCollection('foo'),
+            $this->createArray('foo'),
             [
                 'bar' => new CopyContext('foo'),
             ]
         ))->setMapper(new Mapper);
 
-        self::assertSame($this->createCollection('bar'), $collection([]));
+        self::assertSame($this->createArray('bar'), $collection([]));
     }
 
-    private function createCollection($key)
+    private function createArray($key)
     {
-        return array_map(
-            function ($number) use ($key) {
-                return [$key => $number];
-            },
-            range(1, 10)
+        return array_combine(
+            // Keys must not change.
+            range('a', 'j'),
+            array_map(
+                function ($number) use ($key) {
+                    return [$key => $number];
+                },
+                range('k', 't')
+            )
         );
     }
 }

test/Integration/Mapper/Strategy/CopyKeyTest.php

@@ -0,0 +1,38 @@
+<?php
+namespace ScriptFUSIONTest\Integration\Mapper\Strategy;
+
+use ScriptFUSION\Mapper\Mapper;
+use ScriptFUSION\Mapper\Strategy\Collection;
+use ScriptFUSION\Mapper\Strategy\Copy;
+use ScriptFUSION\Mapper\Strategy\CopyKey;
+
+final class CopyKeyTest extends \PHPUnit_Framework_TestCase
+{
+    public function test()
+    {
+        $mapped = (new Mapper)->map(
+            [
+                'foo' => 'bar',
+                'baz' => [
+                    'qux' => 'quux',
+                    'corge' => 123,
+                ],
+            ],
+            [
+                'foo' => new CopyKey,
+                'bar' => new Collection(
+                    new Copy('baz'),
+                    new CopyKey
+                ),
+            ]
+        );
+
+        self::assertSame([
+            'foo' => null,
+            'bar' => [
+                'qux' => 'qux',
+                'corge' => 'corge',
+            ],
+        ], $mapped);
+    }
+}

test/Unit/Mapper/Strategy/CopyKeyTest.php

@@ -0,0 +1,15 @@
+<?php
+namespace ScriptFUSIONTest\Unit\Mapper\Strategy;
+
+use ScriptFUSION\Mapper\Strategy\CopyKey;
+
+final class CopyKeyTest extends \PHPUnit_Framework_TestCase
+{
+    public function testRoundTrip()
+    {
+        $copyKey = new CopyKey;
+        $copyKey->setKey($key = 'foo');
+
+        self::assertSame($key, $copyKey([]));
+    }
+}