[Arrays] Allow to define a key of next level elements in a function that returns elements from given level

CHANGELOG.md

@@ -2,13 +2,17 @@
 
 Common and useful classes, methods, exceptions etc.
 
+# 1.1.7
+
+1. [Arrays] Allow to define a key of next level elements in a function that returns elements from given level
+
 # 1.1.6
 
 1. [Arrays] Function that returns elements from given level
 
 # 1.1.5
 
-1. [BaseCollection] Prepare elements while adding them by `addMultiple()` method in the same way as passing them in 
+1. [BaseCollection] Prepare elements while adding them by `addMultiple()` method in the same way as passing them in
    constructor.
 
 # 1.1.4

src/Utilities/Arrays.php

@@ -1642,7 +1642,7 @@ class Arrays
         return '' === trim(implode('', $array));
     }
 
-    public static function getElementsFromLevel(array $array, int $level): ?array
+    public static function getElementsFromLevel(array $array, int $level, ?string $childrenKey = null): ?array
     {
         if (empty($array) || $level <= 0) {
             return null;
@@ -1650,11 +1650,16 @@ class Arrays
 
         $result = [];
 
-        foreach ($array as $value) {
-            // This is the expected level (the deepest). Comparing with 1, because level will be decreased by 1, and
-            // finally we will get the latest/deepest level that equals 1.
+        foreach ($array as $key => $value) {
+            // This is the expected level (the deepest). Comparing with 1, because level will be decreased by 1 (later),
+            // and finally we will get the latest/deepest level that equals 1.
             if ($level === 1) {
-                $result[] = $value;
+                // No key of children (next level) provided or this is the same key as processed?
+                // We've got the expected value
+                if ($childrenKey === null || $key === $childrenKey) {
+                    $result[] = $value;
+                }
+
                 continue;
             }
 
@@ -1663,8 +1668,8 @@ class Arrays
                 continue;
             }
 
-            // Let's dive one level down
-            $elements = self::getElementsFromLevel($value, $level - 1);
+            // Let's dive one level down/deeper
+            $elements = self::getElementsFromLevel($value, $level - 1, $childrenKey);
 
             if ($elements === null) {
                 continue;

tests/Utilities/ArraysTest.php

@@ -1645,6 +1645,73 @@ letsTest[2] = value_2;';
         self::assertSame($expectedLevel3, Arrays::getElementsFromLevel($array, 3));
     }
 
+    public function testGetElementsFromLevelIfGivenKeyDoesNotExist(): void
+    {
+        $array = [
+            'test1' => [1, 2, 3],
+            'test2' => [4, 5, 6],
+            'test3' => [
+                'xy',
+                'test4' => [7, 8, 9],
+                'test5' => [
+                    'test6' => [10, 11, 12],
+                ],
+            ],
+        ];
+
+        self::assertSame([], Arrays::getElementsFromLevel($array, 2, 'X'));
+    }
+
+    public function testGetElementsFromLevelWithGivenKey(): void
+    {
+        $array = [
+            // Level 1:
+            [
+                'a',
+                'b',
+
+                // Level 2:
+                'c' => [
+                    1,
+                    2,
+                    'c' => [
+                        4,
+                        5,
+                    ],
+                ],
+            ],
+
+            // Level 1:
+            [
+                'd',
+                'e',
+
+                // Level 2:
+                'c' => [
+                    6,
+                    7,
+                ],
+            ],
+        ];
+
+        $expected = [
+            [
+                1,
+                2,
+                'c' => [
+                    4,
+                    5,
+                ],
+            ],
+            [
+                6,
+                7,
+            ],
+        ];
+
+        self::assertSame($expected, Arrays::getElementsFromLevel($array, 2, 'c'));
+    }
+
     /**
      * Provides simple array to set/replace values with keys
      *