Added TryCatchStrategy and accompanying test and documentation.

Author: a-barzanti

README.md

@@ -34,9 +34,10 @@ Contents
     10. [Merge](#merge)
     11. [TakeFirst](#takefirst)
     12. [ToList](#tolist)
-    13. [Type](#type)
-    14. [Unique](#unique)
-    15. [Walk](#walk)
+    13. [TryCatch](#trycatch)
+    14. [Type](#type)
+    15. [Unique](#unique)
+    16. [Walk](#walk)
   5. [Requirements](#requirements)
   6. [Limitations](#limitations)
   7. [Testing](#testing)
@@ -649,6 +650,44 @@ ToList(Strategy|Mapping|array|mixed $expression)
 
 > ['bar']
 
+### TryCatch
+
+Uses the handler callback to catch and manage any exception thrown by the primary strategy, if an exception was raised delegates to a fallback expression.
+
+It is possible to use nested TryCatch strategies to manage different types of exceptions.
+
+#### Signature
+
+```php
+TryCatch(Strategy $strategy, callable $handler, Strategy|Mapping|array|mixed $expression)
+```
+
+ 1. `$strategy` – Primary Strategy that might raise an exception.
+ 2. `$handler` – Handler function that receives the raised exception as its first argument.
+ 1. `$expression` – Expression.
+
+#### Examples
+
+```php
+(new Mapper)->map(
+    [],
+    new TryCatch(
+        new Callback(
+            function ($data, $context) {
+                throw new \LogicException;
+            }
+        ),
+        function (\Exception $e) {
+            if (! $e instanceof \LogicException) {
+                throw $e;
+            }
+        },
+        'LogicExceptionHandled'
+    )
+);
+```
+> 'LogicExceptionHandled'
+
 ### Type
 
 Casts data to the specified type.

src/Strategy/TryCatch.php

@@ -0,0 +1,38 @@
+<?php
+namespace ScriptFUSION\Mapper\Strategy;
+
+use ScriptFUSION\Mapper\Mapping;
+
+/**
+ * TryCatch uses the handler callback to catch and manage any exception thrown by
+ * the primary strategy, if an exception was raised delegates to a fallback expression.
+ */
+class TryCatch extends Decorator
+{
+    private $expression;
+    private $handler;
+
+    /**
+     * @param Strategy $strategy
+     * @param callable $handler
+     * @param Strategy|Mapping|array|mixed $expression
+     */
+    public function __construct(Strategy $strategy, callable $handler, $expression)
+    {
+        parent::__construct($strategy);
+
+        $this->handler = $handler;
+        $this->expression = $expression;
+    }
+
+    public function __invoke($data, $context = null)
+    {
+        try {
+            return parent::__invoke($data, $context);
+        } catch (\Exception $e) {
+            call_user_func($this->handler, $e);
+
+            return $this->delegate($this->expression, $data, $context);
+        }
+    }
+}

test/Integration/Mapper/Strategy/TryCatchTest.php

@@ -0,0 +1,74 @@
+<?php
+namespace ScriptFUSIONTest\Unit\Mapper\Strategy;
+
+use ScriptFUSION\Mapper\Mapper;
+use ScriptFUSION\Mapper\Strategy\Callback;
+use ScriptFUSION\Mapper\Strategy\TryCatch;
+
+final class TryCatchTest extends \PHPUnit_Framework_TestCase
+{
+    private $callback;
+
+    protected function setUp()
+    {
+        $this->callback = new Callback(function ($data) {
+            if ($data[0] === 'LogicError') {
+                throw new \LogicException('Test Logic Exception');
+            }
+            if ($data[0] === 'DomainError') {
+                throw new \DomainException('Test Domain Exception');
+            }
+
+            return $data;
+        });
+    }
+
+    public function testTryCatch()
+    {
+        /** @var TryCatch $tryCatch */
+        $tryCatch = (
+            new TryCatch(
+                $this->callback,
+                function (\Exception $e) {
+                    if (! $e instanceof \DomainException) {
+                        throw $e;
+                    }
+                },
+                'ExceptionHandled'
+            )
+        )->setMapper(new Mapper);
+
+        self::assertSame(['foo', 'bar'], $tryCatch(['foo', 'bar']));
+        self::assertSame('ExceptionHandled', $tryCatch(['DomainError', 'foo']));
+        $this->setExpectedException(\LogicException::class);
+        self::assertNotEquals('ExceptionHandled', $tryCatch(['LogicError', 'foo']));
+    }
+
+    public function testMultipleTryCatch()
+    {
+        /** @var TryCatch $tryCatch */
+        $tryCatch = (
+            new TryCatch(
+                new TryCatch(
+                    $this->callback,
+                    function (\Exception $e) {
+                        if (! $e instanceof \DomainException) {
+                            throw $e;
+                        }
+                    },
+                    'DomainExceptionHandled'
+                ),
+                function (\Exception $e) {
+                    if (! $e instanceof \LogicException) {
+                        throw $e;
+                    }
+                },
+                'LogicExceptionHandled'
+            )
+        )->setMapper(new Mapper);
+
+        self::assertSame(['foo', 'bar'], $tryCatch(['foo', 'bar']));
+        self::assertSame('LogicExceptionHandled', $tryCatch(['LogicError', 'foo']));
+        self::assertSame('DomainExceptionHandled', $tryCatch(['DomainError', 'foo']));
+    }
+}