Add ArrayHelper::restrictedMerge()

CHANGELOG.md

@@ -2,7 +2,8 @@
 
 ## 3.0.1 under development
 
-- no changes in this release.
+- New #139: Add `ArrayHelper::restrictedMerge()` method that allow to merge two or more arrays recursively with
+  specified depth (@vjik)
 
 ## 3.0.0 January 12, 2023
 

README.md

@@ -87,6 +87,7 @@ Overall the helper has the following method groups.
 - filter
 - map
 - merge
+- restrictedMerge
 - toArray
 
 ### Other

src/ArrayHelper.php

@@ -124,39 +124,34 @@
     }
 
     /**
-     * Merges two or more arrays into one recursively.
-     * If each array has an element with the same string key value, the latter
-     * will overwrite the former (different from {@see array_merge_recursive()}).
-     * Recursive merging will be conducted if both arrays have an element of array
-     * type and are having the same key.
-     * For integer-keyed elements, the elements from the latter array will
-     * be appended to the former array.
+     * Merges two or more arrays into one recursively. If each array has an element with the same string key value,
+     * the latter will overwrite the former (different from {@see array_merge_recursive()}). Recursive merging will be
+     * conducted if both arrays have an element of array type and are having the same key. For integer-keyed elements,
+     * the elements from the latter array will be appended to the former array.
      *
      * @param array ...$arrays Arrays to be merged.
      *
      * @return array The merged array (the original arrays are not changed).
      */
     public static function merge(...$arrays): array
     {
-        $result = array_shift($arrays) ?: [];
-        while (!empty($arrays)) {
-            foreach (array_shift($arrays) as $key => $value) {
-                if (is_int($key)) {
-                    if (array_key_exists($key, $result)) {
-                        if ($result[$key] !== $value) {
-                            $result[] = $value;
-                        }
-                    } else {
-                        $result[$key] = $value;
-                    }
-                } elseif (isset($result[$key]) && is_array($value) && is_array($result[$key])) {
-                    $result[$key] = self::merge($result[$key], $value);
-                } else {
-                    $result[$key] = $value;
-                }
-            }
-        }
-        return $result;
+        return self::doMerge($arrays, null);
+    }
+
+    /**
+     * Merges two or more arrays into one recursively with specified depth. If each array has an element with the same
+     * string key value, the latter will overwrite the former (different from {@see array_merge_recursive()}).
+     * Recursive merging will be conducted if both arrays have an element of array type and are having the same key.
+     * For integer-keyed elements, the elements from the latter array will be appended to the former array.
+     *
+     * @param array[] $arrays Arrays to be merged.
+     * @param int|null $depth The maximum depth that merging is recursively. `Null` means unlimited depth.
+     *
+     * @return array The merged array (the original arrays are not changed).
+     */
+    public static function restrictedMerge(array $arrays, ?int $depth): array
+    {
+        return self::doMerge($arrays, $depth);
     }
 
     /**
@@ -742,7 +737,7 @@
         foreach ($array as $element) {
             if (!is_array($element) && !is_object($element)) {
                 throw new InvalidArgumentException(
                     'index() can not get value from ' . gettype($element) .
                     '. The $array should be either multidimensional array or an array of objects.'
                 );
             }
@@ -926,7 +921,7 @@
      *
      * @return bool Whether the array contains the specified key.
      */
     public static function keyExists(array $array, array|float|int|string $key, bool $caseSensitive = true): bool
     {
         if (is_array($key)) {
             if (count($key) === 1) {
@@ -999,7 +994,7 @@
     public static function pathExists(
         array $array,
         array|float|int|string $path,
         bool $caseSensitive = true,
         string $delimiter = '.'
     ): bool {
         return self::keyExists($array, self::parseMixedPath($path, $delimiter), $caseSensitive);
@@ -1300,7 +1295,7 @@
             $numNestedKeys = count($keys) - 1;
             foreach ($keys as $i => $key) {
                 if (!is_array($excludeNode) || !array_key_exists($key, $excludeNode)) {
                     continue 2; // Jump to next filter.
                 }
 
                 if ($i < $numNestedKeys) {
@@ -1308,7 +1303,7 @@
                     $excludeNode = &$excludeNode[$key];
                 } else {
                     unset($excludeNode[$key]);
                     break;
                 }
             }
         }
@@ -1335,6 +1330,37 @@
         return get_object_vars($object);
     }
 
+    /**
+     * @param array[] $arrays
+     */
+    private static function doMerge(array $arrays, ?int $depth, int $currentDepth = 0): array
+    {
+        $result = array_shift($arrays) ?: [];
+        while (!empty($arrays)) {
+            foreach (array_shift($arrays) as $key => $value) {
+                if (is_int($key)) {
+                    if (array_key_exists($key, $result)) {
+                        if ($result[$key] !== $value) {
+                            $result[] = $value;
+                        }
+                    } else {
+                        $result[$key] = $value;
+                    }
+                } elseif (
+                    isset($result[$key])
+                    && ($depth === null || $currentDepth < $depth)
+                    && is_array($value)
+                    && is_array($result[$key])
+                ) {
+                    $result[$key] = self::doMerge([$result[$key], $value], $depth, $currentDepth + 1);
+                } else {
+                    $result[$key] = $value;
+                }
+            }
+        }
+        return $result;
+    }
+
     private static function normalizeArrayKey(mixed $key): string
     {
         return is_float($key) ? NumericHelper::normalize($key) : (string)$key;

tests/ArrayHelper/MergeTest.php

@@ -99,4 +99,149 @@ public function testMergeIntegerKeyedArraysWithSameValue(): void
 
         $this->assertEquals($expected, $result);
     }
+
+    public static function dataRestrictedMerge(): array
+    {
+        return [
+            'unlimited' => [
+                [
+                    'top' => 3,
+                    'n1' => [
+                        'n1-1' => 3,
+                        'n1-2' => 'x',
+                        'n1-3' => 'y',
+                    ],
+                    'n2' => [
+                        'n2-1' => [1, 2, 3, 4],
+                        'n2-2' => 'a',
+                        'more' => [
+                            'more1' => [6, 7, 8, 9],
+                            'more2' => 'b',
+                        ],
+                    ],
+                ],
+                null,
+            ],
+            'without-recursion' => [
+                [
+                    'top' => 3,
+                    'n1' => [
+                        'n1-1' => 3,
+                        'n1-3' => 'y',
+                    ],
+                    'n2' => [
+                        'n2-1' => [3, 4],
+                        'more' => [
+                            'more1' => [8, 9],
+                            'more2' => 'b',
+                        ],
+                    ],
+                ],
+                0,
+            ],
+            'level1' => [
+                [
+                    'top' => 3,
+                    'n1' => [
+                        'n1-1' => 3,
+                        'n1-2' => 'x',
+                        'n1-3' => 'y',
+                    ],
+                    'n2' => [
+                        'n2-1' => [3, 4],
+                        'n2-2' => 'a',
+                        'more' => [
+                            'more1' => [8, 9],
+                            'more2' => 'b',
+                        ],
+                    ],
+                ],
+                1,
+            ],
+            'level2' => [
+                [
+                    'top' => 3,
+                    'n1' => [
+                        'n1-1' => 3,
+                        'n1-2' => 'x',
+                        'n1-3' => 'y',
+                    ],
+                    'n2' => [
+                        'n2-1' => [1, 2, 3, 4],
+                        'n2-2' => 'a',
+                        'more' => [
+                            'more1' => [8, 9],
+                            'more2' => 'b',
+                        ],
+                    ],
+                ],
+                2,
+            ],
+            'level3' => [
+                [
+                    'top' => 3,
+                    'n1' => [
+                        'n1-1' => 3,
+                        'n1-2' => 'x',
+                        'n1-3' => 'y',
+                    ],
+                    'n2' => [
+                        'n2-1' => [1, 2, 3, 4],
+                        'n2-2' => 'a',
+                        'more' => [
+                            'more1' => [6, 7, 8, 9],
+                            'more2' => 'b',
+                        ],
+                    ],
+                ],
+                3,
+            ],
+        ];
+    }
+
+    /**
+     * @dataProvider dataRestrictedMerge
+     */
+    public function testRestrictedMerge(array $expected, ?int $depth): void
+    {
+        $array1 = [
+            'top' => 1,
+            'n1' => [
+                'n1-1' => 1,
+            ],
+            'n2' => [
+                'n2-1' => [1, 2],
+                'n2-2' => 'a',
+                'more' => [
+                    'more1' => [6, 7],
+                    'more2' => 'a',
+                ],
+            ],
+        ];
+        $array2 = [
+            'top' => 2,
+            'n1' => [
+                'n1-1' => 2,
+                'n1-2' => 'x',
+            ],
+            'n2' => [
+                'n2-1' => [3, 4],
+                'more' => [
+                    'more1' => [8, 9],
+                    'more2' => 'b',
+                ],
+            ],
+        ];
+        $array3 = [
+            'top' => 3,
+            'n1' => [
+                'n1-1' => 3,
+                'n1-3' => 'y',
+            ],
+        ];
+
+        $result = ArrayHelper::restrictedMerge([$array1, $array2, $array3], $depth);
+
+        $this->assertSame($expected, $result);
+    }
 }