Added support for strategy-based mappings and accompanying test.

Added support for null literal expressions and accompanying test case.
Added MapperTest.
BCB: Removed ArrayObject from Mapping inheritance chain.

Author: Bilge

README.md

@@ -16,7 +16,8 @@ This supposes we already created a mapping, `MyMapping`, to convert the data.
 
 Mappings
 --------
-Mappings are data transformation descriptions that describe how to convert data from one format to another. Mapping classes are an object wrapper for an array that describes the output format with instructions (hereafter known as *strategies*) that fetch or augment input data. To write a mapping we must know the input data format so we can then write an array that represents the desired output format and decorate it with strategies.
+
+Mappings are data transformation descriptions that describe how to convert data from one format to another. Mappings are an object wrapper for an array that describes the output format with instructions (hereafter known as *strategies*) that fetch or augment input data. To write a mapping we must know the input data format so we can then write an array that represents the desired output format and decorate it with strategies.
 
 ### Example
 
@@ -50,8 +51,9 @@ An expression is a pseudo-type representing the list of valid mapping value type
  2. `Mapping`
  3. Mapping fragment
  4. Scalar
+ 5. `null`
 
-[Strategies](#strategies) are invoked and substituted as described in the following section. Mappings may contain any number of additional embedded mappings or mapping fragments—a mapping fragment is just a mapping described by an array instead of a `Mapping` object. Scalar values (*integer*, *float*, *string* and *boolean*) have no special meaning and are presented verbatim in the output.
+[Strategies](#strategies) are invoked and substituted as described in the following section. Mappings may contain any number of additional embedded mappings or mapping fragments—a mapping fragment is just a mapping described by an array instead of a `Mapping` object. Scalar values (*integer*, *float*, *string* and *boolean*) and `null` have no special meaning and are presented verbatim in the output.
 
 ### Writing a mapping
 
@@ -68,9 +70,14 @@ Strategies are invokable classes that are invoked by Mapper and substituted for
 
 Strategies are basic building blocks from which complex data manipulation chains can be constructed to meet the bespoke requirements of an application. The composition of strategies forms a powerful object composition DSL that allows us to express how to retrieve and augment data to mould it into the desired format.
 
-### Core strategies
+For a complete list of strategies please see the [strategy reference](#strategy-reference).
+
+Strategy reference
+------------------
+
+The following strategies ship with Mapper and provide a suite of commonly used features, as listed below.
 
-Core strategies are those that ship with Mapper and provide a suite of commonly used features, as listed below.
+### Strategy index
 
 #### Fetchers
 
@@ -80,7 +87,7 @@ Core strategies are those that ship with Mapper and provide a suite of commonly
 #### Augmenters
 
  - [Callback](#callback) – Augments data using the specified callback.
- - [Collection](#collection) – Decorates a collection of data by applying a transformation to each datum.
+ - [Collection](#collection) – Maps a collection of data by applying a transformation to each datum.
  - [Context](#context) – Replaces the context for the specified expression.
  - [Either](#either) – Either uses the primary strategy, if it returns non-null, otherwise delegates to a fallback expression.
  - [Filter](#filter) – Filters null values or values rejected by the specified callback.
@@ -189,7 +196,7 @@ Callback(callable $callback)
 
 ### Collection
 
-Decorates a collection of data by applying a transformation to each datum using a callback. The data collection must be an expression that maps to an array otherwise null is returned.
+Maps a collection of data by applying a transformation to each datum using a callback. The data collection must be an expression that maps to an array otherwise null is returned.
 
 #### Signature
 
@@ -523,7 +530,7 @@ Walk(Strategy|Mapping|array|mixed $expression, array|string $path)
 
 Strategies must implement the `Strategy` interface but it is common to extend `Delegate` or `Decorator` because we usually write augmenters which expect another strategy injected into them to provide data. `Delegate` and `Decorator` provide the `delegate()` method, which allows a strategy to evaluate an expression using Mapper, and is usually needed to evaluate the injected strategy. `Delegate` can delegate any expression to Mapper whereas `Decorator` only accepts `Strategy` objects.
 
-It is recommended to name custom strategies with a *Strategy* suffix to help distinguish them from core strategies.
+It is recommended to name custom strategies with a *Strategy* suffix to help distinguish them from stock strategies.
 
 Requirements
 ------------
@@ -537,6 +544,13 @@ Testing
 Mapper is fully unit tested. Run the tests with `bin/test` from a shell. All examples
 in this document can be found in `DocumentationTest`.
 
+Limitations
+-----------
+
+ - Strategies do not know the name of the key they are assigned to because `Mapper` does not forward the key name.
+ - Strategies do not know where they sit in a `Mapping` and therefore cannot traverse a mapping relative to their position.
+ - The `Collection` strategy overwrites context making any previous context inaccessible to descendants.
+
 
   [Releases]: https://github.com/ScriptFUSION/Mapper/releases
   [Version image]: https://poser.pugx.org/scriptfusion/mapper/version "Latest version"

src/AnonymousMapping.php

@@ -1,11 +1,16 @@
 <?php
 namespace ScriptFUSION\Mapper;
 
+use ScriptFUSION\Mapper\Strategy\Strategy;
+
 final class AnonymousMapping extends Mapping
 {
     private $definition;
 
-    public function __construct(array $definition)
+    /**
+     * @param array|Strategy $definition
+     */
+    public function __construct($definition)
     {
         $this->definition = $definition;
 

src/InvalidMappingException.php

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

src/Mapper.php

@@ -4,7 +4,7 @@
 use ScriptFUSION\Mapper\Strategy\Strategy;
 
 /**
- * Maps records according to strategies, mappings and mapping fragments.
+ * Maps records according to expression value types.
  */
 class Mapper
 {
@@ -28,8 +28,8 @@ public function map(array $record, $expression, $context = null)
         } /* Mapping fragment. */
         elseif (is_array($expression)) {
             return $this->mapFragment($record, $expression, $context);
-        } /* Scalar values. */
-        elseif (is_scalar($expression)) {
+        } /* Null or scalar values. */
+        elseif (null === $expression || is_scalar($expression)) {
             return $expression;
         }
 
@@ -47,7 +47,14 @@ public function map(array $record, $expression, $context = null)
      */
     protected function mapMapping(array $record, Mapping $mapping, $context = null)
     {
-        return $this->mapFragment($record, $mapping->getArrayCopy(), $context);
+        $mapped = $this->mapFragment($record, $mapping->toArray(), $context);
+
+        if ($mapping->isWrapped()) {
+            // Unwrap.
+            return $mapped[0];
+        }
+
+        return $mapped;
     }
 
     protected function mapFragment(array $record, array $fragment, $context = null)
@@ -62,7 +69,7 @@ function (&$strategy, $key, array $record) use ($context) {
             return $fragment;
         }
 
-        throw new \Exception; // TODO: Proper exception.
+        throw new \Exception; // TODO: Determine whether this statement is reachable.
     }
 
     /**

src/Mapping.php

@@ -1,23 +1,61 @@
 <?php
 namespace ScriptFUSION\Mapper;
 
+use ScriptFUSION\Mapper\Strategy\Strategy;
+
 /**
  * Represents a mapping of keys and mappable values.
  */
-abstract class Mapping extends \ArrayObject
+abstract class Mapping
 {
+    /**
+     * @var array
+     */
+    private $mapping;
+
+    private $wrapped = false;
+
     /**
      * Initializes this mapping.
      */
     public function __construct()
     {
-        parent::__construct($this->createMapping());
+        /* Array-based mapping. */
+        if (is_array($mapping = $this->createMapping())) {
+            $this->mapping = $mapping;
+        } /* Strategy-based mapping. */
+        elseif ($mapping instanceof Strategy) {
+            $this->mapping = [$mapping];
+            $this->wrapped = true;
+        } else {
+            throw new InvalidMappingException('Invalid mapping: must be array or an instance of Strategy.');
+        }
     }
 
     /**
-     * Creates a mapping of key names and mappable values.
+     * Creates a mapping of key names and expressions or a straegy.
      *
-     * @return array Mapping.
+     * @return array|Strategy Mapping.
      */
     abstract protected function createMapping();
+
+    /**
+     * Converts the mapping to an array.
+     *
+     * @return array
+     */
+    public function toArray()
+    {
+        return $this->mapping;
+    }
+
+    /**
+     * Gets a value indicating whether the mapping has been wrapped in an array.
+     *
+     * @return boolean True if the mapping is wrapped in an outer array, otherwise false.
+     */
+    public function isWrapped()
+    {
+        return $this->wrapped;
+    }
 }

src/Strategy/Collection.php

@@ -4,7 +4,7 @@
 use ScriptFUSION\Mapper\Mapping;
 
 /**
- * Decorates a collection of data by applying a transformation to each datum using a callback.
+ * Maps a collection of data by applying a transformation to each datum using a callback.
  */
 class Collection extends Delegate
 {

test/Functional/StrategyBasedMappingTest.php

@@ -0,0 +1,25 @@
+<?php
+namespace ScriptFUSIONTest\Functional;
+
+use ScriptFUSION\Mapper\AnonymousMapping;
+use ScriptFUSION\Mapper\Mapper;
+use ScriptFUSION\Mapper\Strategy\Merge;
+
+final class StrategyBasedMappingTest extends \PHPUnit_Framework_TestCase
+{
+    public function test()
+    {
+        self::assertSame(
+            ['foo' => 'foo', 'bar' => 'bar'],
+            (new Mapper)->map(
+                [],
+                new AnonymousMapping(
+                    new Merge(
+                        ['foo' => 'foo'],
+                        ['bar' => 'bar']
+                    )
+                )
+            )
+        );
+    }
+}

test/Integration/Mapper/MapperTest.php

@@ -66,6 +66,13 @@ public function provideScalars()
         ];
     }
 
+    public function testMapNull()
+    {
+        $mapped = $this->mapper->map([], $output = ['foo' => null]);
+
+        self::assertSame($output, $mapped);
+    }
+
     public function testMapInvalidObject()
     {
         $this->setExpectedException(InvalidExpressionException::class);

test/Integration/Mapper/MappingTest.php

@@ -0,0 +1,33 @@
+<?php
+namespace ScriptFUSIONTest\Integration\Mapper;
+
+use ScriptFUSION\Mapper\AnonymousMapping;
+use ScriptFUSION\Mapper\InvalidMappingException;
+use ScriptFUSION\Mapper\Mapping;
+use ScriptFUSION\Mapper\Strategy\Strategy;
+
+final class MappingTest extends \PHPUnit_Framework_TestCase
+{
+    public function testArrayBasedMapping()
+    {
+        $mapping = new AnonymousMapping($fragment = ['foo' => 'foo']);
+
+        self::assertSame($fragment, $mapping->toArray());
+        self::assertFalse($mapping->isWrapped());
+    }
+
+    public function testStrategyBasedMapping()
+    {
+        $mapping = new AnonymousMapping($strategy = \Mockery::mock(Strategy::class));
+
+        self::assertSame([$strategy], $mapping->toArray());
+        self::assertTrue($mapping->isWrapped());
+    }
+
+    public function testInvalidMapping()
+    {
+        $this->setExpectedException(InvalidMappingException::class);
+
+        new AnonymousMapping(\Mockery::mock(Mapping::class));
+    }
+}