Allow constructing recursive MapDiffer that uses itself

RELEASE-NOTES.md

@@ -6,6 +6,8 @@ Latest release:
 
 ## Version 3.2 (dev)
 
+* Added ability to construct a recursive `MapDiffer` that uses itself to diff elements (via `MapDiffer::newRecursiveDiffer`)
+* You can now pass non-list-differs as the second constructor argument in `MapDiffer`
 * Deprecated constant `Diff_VERSION`
 
 ## Version 3.1 (2018-04-17)

src/Differ/Differ.php

@@ -10,6 +10,8 @@
 /**
  * Interface for objects that can diff two arrays to an array of DiffOp.
  *
+ * If the diff is done associatively, the differ should implement MapDifferInterface.
+ *
  * @since 0.4
  *
  * @license GPL-2.0+

src/Differ/MapDiffer.php

@@ -23,7 +23,7 @@
  * @license GPL-2.0+
  * @author Jeroen De Dauw < [email protected] >
  */
-class MapDiffer implements Differ, MapDifferInterface {
+class MapDiffer implements MapDifferInterface {
 
 	/**
 	 * @var bool
@@ -33,30 +33,34 @@ class MapDiffer implements Differ, MapDifferInterface {
 	/**
 	 * @var Differ
 	 */
-	private $listDiffer;
+	private $elementDiffer;
 
 	/**
 	 * @var ValueComparer
 	 */
 	private $valueComparer;
 
 	/**
-	 * Create differ for recursive diffs
+	 * The third argument ($comparer) was added in 3.0
 	 */
-	public static function createRecursive( ValueComparer $comparer = null, Differ $listDiffer = null ) {
-		$differ = new self( true, null, $comparer );
-		$differ->listDiffer = $listDiffer ?? $differ;
+	public function __construct( bool $recursively = false, Differ $elementDiffer = null,
+		ValueComparer $comparer = null ) {
 
-		return $differ;
+		$this->recursively = $recursively;
+		$this->elementDiffer = $elementDiffer ?? new ListDiffer();
+		$this->valueComparer = $comparer ?? new StrictComparer();
 	}
 
 	/**
-	 * The third argument ($comparer) was added in 3.0
+	 * Creates a recursive MapDiffer that by default uses itself to diff elements recursively
+	 *
+	 * @since 3.2
 	 */
-	public function __construct( bool $recursively = false, Differ $listDiffer = null, ValueComparer $comparer = null ) {
-		$this->recursively = $recursively;
-		$this->listDiffer = $listDiffer ?? new ListDiffer();
-		$this->valueComparer = $comparer ?? new StrictComparer();
+	public static function newRecursiveDiffer( ValueComparer $comparer = null, Differ $elementDiffer = null ) {
+		$differ = new self( true, null, $comparer );
+		$differ->elementDiffer = $elementDiffer ?? $differ;
+
+		return $differ;
 	}
 
 	/**
@@ -144,7 +148,10 @@ private function getDiffForArrays( array $old, array $new ): Diff {
 			return new Diff( $this->doDiff( $old, $new ), true );
 		}
 
-		return new Diff( $this->listDiffer->doDiff( $old, $new ), $this->listDiffer instanceof MapDifferInterface );
+		return new Diff(
+			$this->elementDiffer->doDiff( $old, $new ),
+			$this->elementDiffer instanceof MapDifferInterface
+		);
 	}
 
 	/**

src/Differ/MapDifferInterface.php

@@ -4,13 +4,14 @@
 namespace Diff\Differ;
 
 /**
- * Interface for differ that can diff two maps.
+ * Differ that diffs associatively (holding the array keys into account).
+ * These differs can produce associative diff operations (changes and diffs).
  *
  * @since 3.2
  *
  * @license GPL-2.0+
  * @author Alexander Borisov < [email protected] >
  */
-interface MapDifferInterface {
+interface MapDifferInterface extends Differ {
 
 }