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 {
+class MapDiffer implements MapDifferInterface {
 
 	/**
 	 * @var bool
@@ -33,7 +33,7 @@ class MapDiffer implements Differ {
 	/**
 	 * @var Differ
 	 */
-	private $listDiffer;
+	private $elementDiffer;
 
 	/**
 	 * @var ValueComparer
@@ -43,12 +43,26 @@ class MapDiffer implements Differ {
 	/**
 	 * The third argument ($comparer) was added in 3.0
 	 */
-	public function __construct( bool $recursively = false, Differ $listDiffer = null, ValueComparer $comparer = null ) {
+	public function __construct( bool $recursively = false, Differ $elementDiffer = null,
+		ValueComparer $comparer = null ) {
+
 		$this->recursively = $recursively;
-		$this->listDiffer = $listDiffer ?? new ListDiffer();
+		$this->elementDiffer = $elementDiffer ?? new ListDiffer();
 		$this->valueComparer = $comparer ?? new StrictComparer();
 	}
 
+	/**
+	 * Creates a recursive MapDiffer that by default uses itself to diff elements recursively
+	 *
+	 * @since 3.2
+	 */
+	public static function newRecursiveDiffer( ValueComparer $comparer = null, Differ $elementDiffer = null ) {
+		$differ = new self( true, null, $comparer );
+		$differ->elementDiffer = $elementDiffer ?? $differ;
+
+		return $differ;
+	}
+
 	/**
 	 * @see Differ::doDiff
 	 *
@@ -134,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 ), false );
+		return new Diff(
+			$this->elementDiffer->doDiff( $old, $new ),
+			$this->elementDiffer instanceof MapDifferInterface
+		);
 	}
 
 	/**

src/Differ/MapDifferInterface.php

@@ -0,0 +1,17 @@
+<?php
+declare( strict_types = 1 );
+
+namespace Diff\Differ;
+
+/**
+ * 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 extends Differ {
+
+}