Polished TryCatch tests and documentation.

Author: Paul

README.md

@@ -294,6 +294,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.
+ - [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.
  - [Walk](#walk) – Walks a nested structure to the specified element in the same manner as `Copy`.
@@ -652,41 +653,42 @@ ToList(Strategy|Mapping|array|mixed $expression)
 
 ### 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.
+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.
 
-It is possible to use nested TryCatch strategies to manage different types of exceptions.
+Different fallback expressions can be used for different exception types by nesting multiple instances of this strategy.
 
 #### 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.
+ 1. `$strategy` – Primary strategy.
+ 2. `$handler` – Exception handler that receives the thrown exception as its first argument.
+ 3. `$expression` – Fallback expression.
 
 #### Examples
 
 ```php
 (new Mapper)->map(
-    [],
+    ['foo' => 'bar'],
     new TryCatch(
         new Callback(
-            function ($data, $context) {
-                throw new \LogicException;
+            function () {
+                throw new \DomainException;
             }
         ),
-        function (\Exception $e) {
-            if (! $e instanceof \LogicException) {
-                throw $e;
+        function (\Exception $exception) {
+            if (!$exception instanceof \DomainException) {
+                throw $exception;
             }
         },
-        'LogicExceptionHandled'
+        new Copy('foo')
     )
 );
 ```
-> 'LogicExceptionHandled'
+
+> 'bar'
 
 ### Type
 

src/Strategy/TryCatch.php

@@ -4,18 +4,20 @@
 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.
+ * Tries the primary strategy and falls back to an expression if an exception is thrown.
  */
 class TryCatch extends Decorator
 {
-    private $expression;
+    /** @var callable */
     private $handler;
 
+    /** @var Strategy|Mapping|array|mixed */
+    private $expression;
+
     /**
-     * @param Strategy $strategy
-     * @param callable $handler
-     * @param Strategy|Mapping|array|mixed $expression
+     * @param Strategy $strategy Primary strategy.
+     * @param callable $handler Exception handler.
+     * @param Strategy|Mapping|array|mixed $expression Fallback expression.
      */
     public function __construct(Strategy $strategy, callable $handler, $expression)
     {
@@ -29,8 +31,8 @@ public function __invoke($data, $context = null)
     {
         try {
             return parent::__invoke($data, $context);
-        } catch (\Exception $e) {
-            call_user_func($this->handler, $e);
+        } catch (\Exception $exception) {
+            call_user_func($this->handler, $exception);
 
             return $this->delegate($this->expression, $data, $context);
         }

test/Functional/DocumentationTest.php

@@ -15,6 +15,7 @@
 use ScriptFUSION\Mapper\Strategy\Merge;
 use ScriptFUSION\Mapper\Strategy\TakeFirst;
 use ScriptFUSION\Mapper\Strategy\ToList;
+use ScriptFUSION\Mapper\Strategy\TryCatch;
 use ScriptFUSION\Mapper\Strategy\Type;
 use ScriptFUSION\Mapper\Strategy\Unique;
 use ScriptFUSION\Mapper\Strategy\Walk;
@@ -247,6 +248,29 @@ public function testToList()
         );
     }
 
+    public function testTryCatch()
+    {
+        self::assertSame(
+            'bar',
+            (new Mapper)->map(
+                ['foo' => 'bar'],
+                new TryCatch(
+                    new Callback(
+                        function () {
+                            throw new \DomainException;
+                        }
+                    ),
+                    function (\Exception $exception) {
+                        if (!$exception instanceof \DomainException) {
+                            throw $exception;
+                        }
+                    },
+                    new Copy('foo')
+                )
+            )
+        );
+    }
+
     public function testType()
     {
         self::assertSame(

test/Integration/Mapper/Strategy/TryCatchTest.php

@@ -12,11 +12,8 @@ final class TryCatchTest extends \PHPUnit_Framework_TestCase
     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');
+            if ($data[0] instanceof \Exception) {
+                throw $data[0];
             }
 
             return $data;
@@ -30,45 +27,49 @@ public function testTryCatch()
             new TryCatch(
                 $this->callback,
                 function (\Exception $e) {
-                    if (! $e instanceof \DomainException) {
+                    if (!$e instanceof \DomainException) {
                         throw $e;
                     }
                 },
-                'ExceptionHandled'
+                $fallback = 'bar'
             )
         )->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']));
+        self::assertSame($data = ['foo'], $tryCatch($data));
+        self::assertSame($fallback, $tryCatch([new \DomainException]));
+
+        $this->setExpectedException(\RuntimeException::class);
+        $tryCatch([new \RuntimeException]);
     }
 
-    public function testMultipleTryCatch()
+    public function testNestedTryCatch()
     {
         /** @var TryCatch $tryCatch */
         $tryCatch = (
             new TryCatch(
                 new TryCatch(
                     $this->callback,
                     function (\Exception $e) {
-                        if (! $e instanceof \DomainException) {
+                        if (!$e instanceof \DomainException) {
                             throw $e;
                         }
                     },
-                    'DomainExceptionHandled'
+                    $innerFallback = 'bar'
                 ),
                 function (\Exception $e) {
-                    if (! $e instanceof \LogicException) {
+                    if (!$e instanceof \LogicException) {
                         throw $e;
                     }
                 },
-                'LogicExceptionHandled'
+                $outerFallback = 'baz'
             )
         )->setMapper(new Mapper);
 
-        self::assertSame(['foo', 'bar'], $tryCatch(['foo', 'bar']));
-        self::assertSame('LogicExceptionHandled', $tryCatch(['LogicError', 'foo']));
-        self::assertSame('DomainExceptionHandled', $tryCatch(['DomainError', 'foo']));
+        self::assertSame($data = ['foo'], $tryCatch($data));
+        self::assertSame($innerFallback, $tryCatch([new \DomainException]));
+        self::assertSame($outerFallback, $tryCatch([new \LogicException]));
+
+        $this->setExpectedException(\RuntimeException::class);
+        $tryCatch([new \RuntimeException]);
     }
 }