Add ability to specify recursion depth for recursive modifier

CHANGELOG.md

@@ -1,8 +1,8 @@
 # Yii Config Change Log
 
-## 1.4.1 under development
+## 1.5.0 under development
 
-- no changes in this release.
+- New #155: Add ability to specify recursion depth for recursive modifier (@vjik)
 
 ## 1.4.0 November 17, 2023
 

README.md

@@ -465,6 +465,12 @@ $config = new Config(
 $params = $config->get('params'); // merged recursively
 ```
 
+If you want to recursively merge arrays to a certain depth, use the `RecursiveMerge::groupsWithDepth()` method:
+
+```php
+RecursiveMerge::groups(['widgets-themes', 'my-custom-group'], 1)
+```
+
 ### Reverse merge of arrays
 
 Result of reverse merge is being ordered descending by data source. It is useful for merging module config with

psalm.xml

@@ -10,4 +10,7 @@
     <projectFiles>
         <directory name="src" />
     </projectFiles>
+    <issueHandlers>
+        <MixedAssignment errorLevel="suppress" />
+    </issueHandlers>
 </psalm>

src/DataModifiers.php

@@ -21,9 +21,9 @@
 final class DataModifiers
 {
     /**
-     * @psalm-var array<string, array-key>
+     * @psalm-var array<string, int|null>
      */
-    private array $recursiveMergeGroupsIndex;
+    private array $mergedGroupsRecursionDepthMap;
 
     /**
      * @psalm-var array<string, array-key>
@@ -55,7 +55,10 @@ public function __construct(array $modifiers = [])
             }
 
             if ($modifier instanceof RecursiveMerge) {
-                array_unshift($recursiveMergeGroups, $modifier->getGroups());
+                array_unshift(
+                    $recursiveMergeGroups,
+                    array_fill_keys($modifier->getGroups(), $modifier->getDepth())
+                );
                 continue;
             }
 
@@ -97,12 +100,22 @@ public function __construct(array $modifiers = [])
         }
 
         $this->reverseMergeGroupsIndex = array_flip(array_merge(...$reverseMergeGroups));
-        $this->recursiveMergeGroupsIndex = array_flip(array_merge(...$recursiveMergeGroups));
+        $this->mergedGroupsRecursionDepthMap = array_merge(...$recursiveMergeGroups);
     }
 
-    public function isRecursiveMergeGroup(string $group): bool
+    /**
+     * @return false|int|null
+     * - `int` - depth limited by specified number.
+     * - `null` - depth is not limited (infinite recursion).
+     * - `false` - recursion is disabled.
+     */
+    public function getRecursionDepth(string $group): int|null|false
     {
-        return array_key_exists($group, $this->recursiveMergeGroupsIndex);
+        if (!array_key_exists($group, $this->mergedGroupsRecursionDepthMap)) {
+            return false;
+        }
+
+        return $this->mergedGroupsRecursionDepthMap[$group];
     }
 
     public function isReverseMergeGroup(string $group): bool

src/Merger.php

@@ -55,19 +55,19 @@ public function reset(): void
      */
     public function merge(Context $context, array $arrayA, array $arrayB): array
     {
-        $isRecursiveMerge = $this->dataModifiers->isRecursiveMergeGroup($context->group());
+        $recursionDepth = $this->dataModifiers->getRecursionDepth($context->group());
         $isReverseMerge = $this->dataModifiers->isReverseMergeGroup($context->group());
 
         if ($isReverseMerge) {
-            $arrayB = $this->prepareArrayForReverse($context, [], $arrayB, $isRecursiveMerge);
+            $arrayB = $this->prepareArrayForReverse($context, [], $arrayB, $recursionDepth !== false);
         }
 
         return $this->performMerge(
             $context,
             [],
             $isReverseMerge ? $arrayB : $arrayA,
             $isReverseMerge ? $arrayA : $arrayB,
-            $isRecursiveMerge,
+            $recursionDepth,
             $isReverseMerge,
         );
     }
@@ -87,19 +87,16 @@ private function performMerge(
         array $recursiveKeyPath,
         array $arrayA,
         array $arrayB,
-        bool $isRecursiveMerge,
-        bool $isReverseMerge
+        int|null|false $recursionDepth,
+        bool $isReverseMerge,
+        int $depth = 0,
     ): array {
         $result = $arrayA;
-
-        /** @psalm-var mixed $v */
         foreach ($arrayB as $k => $v) {
             if (is_int($k)) {
                 if (array_key_exists($k, $result) && $result[$k] !== $v) {
-                    /** @var mixed */
                     $result[] = $v;
                 } else {
-                    /** @var mixed */
                     $result[$k] = $v;
                 }
                 continue;
@@ -108,8 +105,9 @@ private function performMerge(
             $fullKeyPath = array_merge($recursiveKeyPath, [$k]);
 
             if (
-                $isRecursiveMerge
+                $recursionDepth !== false
                 && is_array($v)
+                && ($recursionDepth === null || $depth < $recursionDepth)
                 && (
                     !array_key_exists($k, $result)
                     || is_array($result[$k])
@@ -122,7 +120,15 @@ private function performMerge(
                     $fullKeyPath,
                     $result,
                     $k,
-                    $this->performMerge($context, $fullKeyPath, $array, $v, $isRecursiveMerge, $isReverseMerge)
+                    $this->performMerge(
+                        $context,
+                        $fullKeyPath,
+                        $array,
+                        $v,
+                        $recursionDepth,
+                        $isReverseMerge,
+                        $depth + 1,
+                    )
                 );
                 continue;
             }
@@ -171,10 +177,8 @@ private function prepareArrayForReverse(
     ): array {
         $result = [];
 
-        /** @var mixed $value */
         foreach ($array as $key => $value) {
             if (is_int($key)) {
-                /** @var mixed */
                 $result[$key] = $value;
                 continue;
             }
@@ -194,7 +198,6 @@ private function prepareArrayForReverse(
             }
 
             if ($context->isVariable()) {
-                /** @var mixed */
                 $result[$key] = $value;
                 continue;
             }
@@ -211,7 +214,6 @@ private function prepareArrayForReverse(
                 $this->throwDuplicateKeyErrorException($context->group(), $recursiveKeyPath, [$file, $context->file()]);
             }
 
-            /** @var mixed */
             $result[$key] = $value;
 
             /** @psalm-suppress MixedPropertyTypeCoercion */

src/Modifier/RecursiveMerge.php

@@ -80,9 +80,11 @@ final class RecursiveMerge
 {
     /**
      * @param string[] $groups
+     * @psalm-param positive-int|null $depth
      */
     private function __construct(
         private array $groups,
+        private ?int $depth = null,
     ) {
     }
 
@@ -91,11 +93,28 @@ public static function groups(string ...$groups): self
         return new self($groups);
     }
 
+    /**
+     * @param string[] $groups
+     * @psalm-param positive-int|null $depth
+     */
+    public static function groupsWithDepth(array $groups, ?int $depth): self
+    {
+        return new self($groups, $depth);
+    }
+
     /**
      * @return string[]
      */
     public function getGroups(): array
     {
         return $this->groups;
     }
+
+    /**
+     * @psalm-return positive-int|null
+     */
+    public function getDepth(): ?int
+    {
+        return $this->depth;
+    }
 }