Added Translate strategy and accompanying tests and documentation.

Updated Travis config to test lowest set of dependencies.

Author: Paul

.travis.yml

@@ -11,14 +11,26 @@ php:
   - 7.0
   - 7.1
 
+env:
+  matrix:
+    -
+    - DEPENDENCIES=--prefer-lowest
+
+matrix:
+  fast_finish: true
+
+cache:
+  directories:
+    - .composer/cache
+
 install:
   - alias composer=composer\ -n && composer selfupdate
   - composer validate
-  - composer --prefer-source install
+  - composer update $DEPENDENCIES
 
 script:
   - composer test -- --coverage-clover=build/logs/clover.xml
 
 after_success:
-  - composer --prefer-source require satooshi/php-coveralls
+  - composer require satooshi/php-coveralls
   - vendor/bin/coveralls -v

README.md

@@ -35,6 +35,7 @@ Contents
     1. [Merge](#merge)
     1. [TakeFirst](#takefirst)
     1. [ToList](#tolist)
+    1. [Translate](#translate)
     1. [TryCatch](#trycatch)
     1. [Type](#type)
     1. [Unique](#unique)
@@ -296,6 +297,7 @@ The following strategies ship with Mapper and provide a suite of commonly used f
  - [Merge](#merge) – Merges two data sets together giving precedence to the latter if keys collide.
  - [TakeFirst](#takefirst) – Takes the first value from a collection one or more times.
  - [ToList](#tolist) – Converts data to a single-element list unless it is already a list.
+ - [Translate](#translate) – Translates a value using a mapping.
  - [TryCatch](#trycatch) – Tries the primary strategy and falls back to an expression if an exception is thrown.
  - [Type](#type) – Casts data to the specified type.
  - [Unique](#unique) – Creates a collection of unique values by removing duplicates.
@@ -683,6 +685,33 @@ ToList(Strategy|Mapping|array|mixed $expression)
 
 > ['bar']
 
+### Translate
+
+Translates a value using a mapping. The mapping may derived from any valid expression.
+
+#### Signature
+
+```php
+Translate(Strategy $value, Strategy|Mapping|array|mixed $mapping)
+```
+
+ 1. `$value` – Value used to match against an entry in the mapping.
+ 2. `$mapping` – Mapping that specifies what the value may be translated to.
+
+#### Example
+
+```php
+(new Mapper)->map(
+    ['foo' => 'foo'],
+    new Translate(
+        new Copy('foo'),
+        ['foo' => 'bar']
+    )
+);
+```
+
+> 'bar'
+
 ### TryCatch
 
 Tries the primary strategy and falls back to an expression if an exception is thrown. The thrown exception is passed to the specified exception handler. The handler should throw an exception if it does not expect the exception type it receives.

composer.json

@@ -15,8 +15,8 @@
   },
   "require-dev": {
     "scriptfusion/static-class": "^1",
-    "phpunit/phpunit": "^4",
-    "mockery/mockery": "^0"
+    "phpunit/phpunit": "^4.8",
+    "mockery/mockery": "^0.9.4"
   },
   "autoload": {
     "psr-4": {

src/DataType.php

@@ -5,6 +5,13 @@
 
 /**
  * Specifies a PHP data type.
+ *
+ * @method static BOOLEAN()
+ * @method static INTEGER()
+ * @method static FLOAT()
+ * @method static STRING()
+ * @method static MAP()
+ * @method static OBJECT()
  */
 final class DataType extends AbstractEnumeration
 {

src/Strategy/Translate.php

@@ -0,0 +1,35 @@
+<?php
+namespace ScriptFUSION\Mapper\Strategy;
+
+use ScriptFUSION\Mapper\Mapping;
+
+/**
+ * Translates a value using a mapping.
+ */
+class Translate extends Decorator
+{
+    private $mapping;
+
+    /**
+     * Initializes this instance with the specified value and mapping.
+     *
+     * @param Strategy $value Value used to match against an entry in the mapping.
+     * @param Strategy|Mapping|array|mixed $mapping Mapping that specifies what the value may be translated to.
+     */
+    public function __construct(Strategy $value, $mapping)
+    {
+        parent::__construct($value);
+
+        $this->mapping = $mapping;
+    }
+
+    public function __invoke($data, $context = null)
+    {
+        $value = parent::__invoke($data, $context);
+        $mapping = $this->delegate($this->mapping, $data, $context);
+
+        if (is_array($mapping) && array_key_exists($value, $mapping)) {
+            return $mapping[$value];
+        }
+    }
+}

test/Functional/DocumentationTest.php

@@ -16,6 +16,7 @@
 use ScriptFUSION\Mapper\Strategy\Merge;
 use ScriptFUSION\Mapper\Strategy\TakeFirst;
 use ScriptFUSION\Mapper\Strategy\ToList;
+use ScriptFUSION\Mapper\Strategy\Translate;
 use ScriptFUSION\Mapper\Strategy\TryCatch;
 use ScriptFUSION\Mapper\Strategy\Type;
 use ScriptFUSION\Mapper\Strategy\Unique;
@@ -267,6 +268,20 @@ public function testToList()
         );
     }
 
+    public function testTranslate()
+    {
+        self::assertSame(
+            'bar',
+            (new Mapper)->map(
+                ['foo' => 'foo'],
+                new Translate(
+                    new Copy('foo'),
+                    ['foo' => 'bar']
+                )
+            )
+        );
+    }
+
     public function testTryCatch()
     {
         self::assertSame(

test/Integration/Mapper/Strategy/TranslateTest.php

@@ -0,0 +1,26 @@
+<?php
+namespace ScriptFUSIONTest\Integration\Mapper\Strategy;
+
+use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;
+use ScriptFUSION\Mapper\Mapper;
+use ScriptFUSION\Mapper\Strategy\Translate;
+use ScriptFUSIONTest\MockFactory;
+
+final class TranslateTest extends \PHPUnit_Framework_TestCase
+{
+    use MockeryPHPUnitIntegration;
+
+    public function testValueFound()
+    {
+        $translate = (new Translate(MockFactory::mockStrategy('foo'), ['foo' => 'bar']))->setMapper(new Mapper);
+
+        self::assertSame('bar', $translate([]));
+    }
+
+    public function testValueNotFound()
+    {
+        $translate = (new Translate(MockFactory::mockStrategy('foo'), ['bar' => 'bar']))->setMapper(new Mapper);
+
+        self::assertNull($translate([]));
+    }
+}

test/MockFactory.php

@@ -3,12 +3,23 @@
 
 use Mockery\MockInterface;
 use ScriptFUSION\Mapper\Mapper;
+use ScriptFUSION\Mapper\Strategy\Strategy;
 use ScriptFUSION\StaticClass;
 
 final class MockFactory
 {
     use StaticClass;
 
+    /**
+     * @param mixed $data
+     *
+     * @return Strategy|MockInterface
+     */
+    public static function mockStrategy($data)
+    {
+        return \Mockery::mock(Strategy::class)->shouldReceive('__invoke')->andReturn($data)->getMock();
+    }
+
     /**
      * @param mixed $data
      *