Added Debug strategy and accompanying test.

README.md

@@ -22,9 +22,15 @@ Contents
   1. [Strategies](#strategies)
   1. [Practical example](#practical-example)
   1. [Strategy reference](#strategy-reference)
+
+      [Fetchers](#fetchers)
+
       1. [Copy](#copy)
       1. [CopyContext](#copycontext)
       1. [CopyKey](#copykey)
+
+      [Augmenters](#augmenters)
+
       1. [Callback](#callback)
       1. [Collection](#collection)
       1. [Context](#context)
@@ -42,6 +48,10 @@ Contents
       1. [Type](#type)
       1. [Unique](#unique)
       1. [Walk](#walk)
+
+      [Others](#others)
+
+      1. [Debug](#debug)
   1. [Requirements](#requirements)
   1. [Limitations](#limitations)
   1. [Testing](#testing)
@@ -307,6 +317,10 @@ The following strategies ship with Mapper and provide a suite of commonly used f
  - [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`.
 
+#### Others
+
+ - [Debug](#debug) – 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.
@@ -843,7 +857,7 @@ Creates a collection of unique values by removing duplicates.
 Unique(Strategy|Mapping|array|mixed $collection)
 ```
 
- 1. `$collection` – Expression the maps to an array.
+ 1. `$collection` – Expression that maps to an array.
 
 #### Example
 
@@ -886,6 +900,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` – Expression to delegate to `Mapper`.
+
 Requirements
 ------------
 
@@ -916,3 +944,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

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();
+        }
+    }
+}

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;
+    }
+}