From 361843ef20a807d0bff6b9b11afed210475e1f9a Mon Sep 17 00:00:00 2001
From: Paul <paul.morris@lifeworks.com>
Date: Wed, 7 Jun 2017 11:22:57 +0100
Subject: [PATCH] Added Debug strategy and accompanying test.

---
 README.md                                     | 68 +++++++++++++------
 src/Strategy/Debug.php                        | 30 ++++++++
 .../Integration/Mapper/Strategy/DebugTest.php | 50 ++++++++++++++
 3 files changed, 126 insertions(+), 22 deletions(-)
 create mode 100644 src/Strategy/Debug.php
 create mode 100644 test/Integration/Mapper/Strategy/DebugTest.php

diff --git a/README.md b/README.md
index a2f1c9a..e6b234d 100644
--- a/README.md
+++ b/README.md
@@ -22,26 +22,30 @@ Contents
   1. [Strategies](#strategies)
   1. [Practical example](#practical-example)
   1. [Strategy reference](#strategy-reference)
-      1. [Copy](#copy)
-      1. [CopyContext](#copycontext)
-      1. [CopyKey](#copykey)
-      1. [Callback](#callback)
-      1. [Collection](#collection)
-      1. [Context](#context)
-      1. [Either](#either)
-      1. [Filter](#filter)
-      1. [Flatten](#flatten)
-      1. [IfElse](#ifelse)
-      1. [IfExists](#ifexists)
-      1. [Join](#join)
-      1. [Merge](#merge)
-      1. [TakeFirst](#takefirst)
-      1. [ToList](#tolist)
-      1. [Translate](#translate)
-      1. [TryCatch](#trycatch)
-      1. [Type](#type)
-      1. [Unique](#unique)
-      1. [Walk](#walk)
+      1. [Fetchers](#fetchers)
+          1. [Copy](#copy)
+          1. [CopyContext](#copycontext)
+          1. [CopyKey](#copykey)
+      1. [Augmenters](#augmenters)
+          1. [Callback](#callback)
+          1. [Collection](#collection)
+          1. [Context](#context)
+          1. [Either](#either)
+          1. [Filter](#filter)
+          1. [Flatten](#flatten)
+          1. [IfElse](#ifelse)
+          1. [IfExists](#ifexists)
+          1. [Join](#join)
+          1. [Merge](#merge)
+          1. [TakeFirst](#takefirst)
+          1. [ToList](#tolist)
+          1. [Translate](#translate)
+          1. [TryCatch](#trycatch)
+          1. [Type](#type)
+          1. [Unique](#unique)
+          1. [Walk](#walk)
+      1. [Others](#others)
+          1. [Debug](#debug)
   1. [Requirements](#requirements)
   1. [Limitations](#limitations)
   1. [Testing](#testing)
@@ -307,6 +311,10 @@ The following strategies ship with Mapper and provide a suite of commonly used f
  - [Unique](#unique) &ndash; Creates a collection of unique values by removing duplicates.
  - [Walk](#walk) &ndash; Walks a nested structure to the specified element in the same manner as `Copy`.
 
+#### Others
+
+ - [Debug](#debug) &ndash; Debugs a mapping by breaking the debugger wherever this strategy is inserted.
+
 ### Copy
 
 Copy copies a portion of the input data with support for nested structures.
@@ -329,7 +337,7 @@ $data = [
         'bar' => 123,
     ],
 ];
-	
+
 (new Mapper)->map($data, new Copy('foo'));
 ```
 
@@ -843,7 +851,7 @@ Creates a collection of unique values by removing duplicates.
 Unique(Strategy|Mapping|array|mixed $collection)
 ```
 
- 1. `$collection` &ndash; Expression the maps to an array.
+ 1. `$collection` &ndash; Expression that maps to an array.
 
 #### Example
 
@@ -886,6 +894,20 @@ Walk(Strategy|Mapping|array|mixed $expression, array|string $path)
 
 > 123
 
+### Debug
+
+Debugs a mapping by breaking the debugger wherever this strategy is inserted. The specified expression will be mapped immediately before triggering the breakpoint. The debugger should see the current data, context and mapped expression.
+
+Currently only the [Xdebug][Xdebug] debugger is supported.
+
+#### Signature
+
+```php
+Debug(Strategy|Mapping|array|mixed $expression)
+```
+
+ 1. `$expression` &ndash; Expression to delegate to `Mapper`.
+
 Requirements
 ------------
 
@@ -916,3 +938,5 @@ in this document can be found in `DocumentationTest`.
   [Coverage image]: https://coveralls.io/repos/ScriptFUSION/Mapper/badge.svg "Test coverage"
   [Style]: https://styleci.io/repos/59734709
   [Style image]: https://styleci.io/repos/59734709/shield?style=flat "Code style"
+
+  [Xdebug]: https://xdebug.org
diff --git a/src/Strategy/Debug.php b/src/Strategy/Debug.php
new file mode 100644
index 0000000..a20442c
--- /dev/null
+++ b/src/Strategy/Debug.php
@@ -0,0 +1,30 @@
+<?php
+namespace ScriptFUSION\Mapper\Strategy;
+
+/**
+ * Debugs a mapping by breaking the debugger wherever this strategy is inserted.
+ */
+final class Debug extends Delegate
+{
+    public function __construct($expression = null)
+    {
+        parent::__construct($expression);
+    }
+
+    public function __invoke($data, $context = null)
+    {
+        $mapped = parent::__invoke($data, $context);
+
+        self::debug($data, $context, $mapped);
+
+        return $mapped;
+    }
+
+    // Although all these parameters are unused, it is helpful to have relevant data in the current stack frame.
+    private static function debug($data, $context, $mapped)
+    {
+        if (function_exists('xdebug_break')) {
+            xdebug_break();
+        }
+    }
+}
diff --git a/test/Integration/Mapper/Strategy/DebugTest.php b/test/Integration/Mapper/Strategy/DebugTest.php
new file mode 100644
index 0000000..2b44ea0
--- /dev/null
+++ b/test/Integration/Mapper/Strategy/DebugTest.php
@@ -0,0 +1,50 @@
+<?php
+namespace ScriptFUSIONTest\Integration\Mapper\Strategy {
+
+    use ScriptFUSION\Mapper\Mapper;
+    use ScriptFUSION\Mapper\Strategy\Copy;
+    use ScriptFUSION\Mapper\Strategy\Debug;
+
+    final class DebugTest extends \PHPUnit_Framework_TestCase
+    {
+        public static $debugged;
+
+        protected function setUp()
+        {
+            self::$debugged = false;
+        }
+
+        /**
+         * Tests that expressions are delegated to Mapper.
+         */
+        public function testDelegation()
+        {
+            $debug = (new Debug(new Copy(0)))->setMapper(new Mapper);
+
+            self::assertSame($record = 'foo', $debug([$record]));
+        }
+
+        /**
+         * Tests that the Xdebug breakpoint is called.
+         */
+        public function testXdebug()
+        {
+            $debug = (new Debug)->setMapper(new Mapper);
+
+            $debug([]);
+
+            self::assertTrue(self::$debugged);
+        }
+    }
+}
+
+// Mock debugging functions.
+namespace ScriptFUSION\Mapper\Strategy {
+
+    use ScriptFUSIONTest\Integration\Mapper\Strategy\DebugTest;
+
+    function xdebug_break()
+    {
+        DebugTest::$debugged = true;
+    }
+}