Unpack method refactor and isAssoc documentation improvement

Author: minwork

README.md

@@ -45,7 +45,7 @@ Here, you can quickly get started by becoming familiar with each and every metho
 * [hasKeys](#haskeysarray-array-mixed-keys-bool-strict--false-bool)
 * [getNestedElement](#getnestedelementarrayarrayaccess-array-mixed-keys-mixed-default--null-mixed)
 * [setNestedElement](#setnestedelementarray-array-mixed-keys-mixed-value-array)
-* [unpack](#unpackarray-array-array-keys---array)
+* [unpack](#unpackarray-array-int-mode--arrunpack_all-array)
 ### Validation
 * [check](#checkarray-array-mixedcallable-condition-bool-strict--false-bool)
 * [isEmpty](#isemptymixed-array-bool)
@@ -159,7 +159,7 @@ Arr::setNestedElement($array, 'foo.[].foo', 'bar') ->
 Arr::setNestedElement([], '[].[].[]', 'test') -> [ [ [ 'test' ] ] ]
 ```
 
-### `unpack(array $array, array $keys = []): array`
+### `unpack(array $array, int $mode = Arr::UNPACK_ALL): array`
 Converts multidimensional array to map of keys concatenated by dot and corresponding values
 
 ```php

src/Arr.php

@@ -32,8 +32,22 @@ class Arr
     const MAP_ARRAY_VALUE_KEYS_LIST = 2;
     const MAP_ARRAY_KEYS_ARRAY_VALUE = 4;
 
+    const UNPACK_ALL = 1;
+    /**
+     * Preserve arrays with highest nesting level (if they are not assoc) as element values instead of unpacking them
+     */
+    const UNPACK_PRESERVE_LIST_ARRAY = 2;
+    /**
+     * Preserve arrays with highest nesting level (if they are assoc) as element values instead of unpacking them
+     */
+    const UNPACK_PRESERVE_ASSOC_ARRAY = 4;
+    /**
+     * Preserve all arrays with highest nesting level as element values instead of unpacking them
+     */
+    const UNPACK_PRESERVE_ARRAY = 8;
 
     private const AUTO_INDEX_KEY = '[]';
+    private const KEY_SEPARATOR = '.';
 
     /*--------------------------------------------------------------------------------------*\
      |                                        Common                                        |
@@ -58,7 +72,7 @@ class Arr
     public static function getKeysArray($keys): array
     {
         if (is_string($keys)) {
-            return empty($keys) ? [] : explode('.', $keys);
+            return empty($keys) ? [] : explode(self::KEY_SEPARATOR, $keys);
         }
         return is_null($keys) ? [] : array_filter(array_values(self::forceArray($keys)), function ($value) {
             return $value !== null && $value !== '' && (is_string($value) || is_int($value));
@@ -153,21 +167,34 @@ public static function setNestedElement(array $array, $keys, $value): array
      * Converts multidimensional array to map of keys concatenated by dot and corresponding values
      *
      * @param array $array
-     * @param array $keys Internal keys storage used for recursive calls
+     * @param int $mode Modify behaviour of unpack (see description of Arr::UNPACK_ constants)
      * @return array
      */
-    public static function unpack(array $array, array $keys = []): array
+    public static function unpack(array $array, int $mode = self::UNPACK_ALL): array
+    {
+        return self::_unpack($array, $mode);
+    }
+
+    private static function _unpack(array $array, int $mode = self::UNPACK_ALL, array $keys = []): array
     {
         $result = [];
 
         foreach ($array as $key => $value) {
 
-            if (is_array($value)) {
+            if (is_array($value) && !(
+                    // Check if value IS NOT a subject for preserve mode
+                    !self::isNested($value) && // Preserve mode only work for highest depth elements
+                    (
+                        ($mode === self::UNPACK_PRESERVE_LIST_ARRAY && !self::isAssoc($value, true)) ||
+                        ($mode === self::UNPACK_PRESERVE_ASSOC_ARRAY && self::isAssoc($value, true)) ||
+                        $mode === self::UNPACK_PRESERVE_ARRAY
+                    )
+                )) {
                 $keys[] = $key;
-                $result += self::unpack($value, $keys);
+                $result += self::_unpack($value, $mode, $keys);
                 array_pop($keys);
             } else {
-                $result[implode('.', array_merge($keys, [$key]))] = $value;
+                $result[implode(self::KEY_SEPARATOR, array_merge($keys, [$key]))] = $value;
             }
         }
 
@@ -251,7 +278,9 @@ public static function isEmpty($array): bool
      *
      * @param array $array
      * @param bool $strict
-     *            If false then this function will match any array that doesn't contain integer keys
+     * <p>If <i>false</i> then this function will match any array that doesn't contain integer keys.</p>
+     * <p>If <i>true</i> then this function match only arrays with sequence of integers starting from zero (range from 0 to elements_number - 1) as keys.</p>
+     *
      * @return boolean
      */
     public static function isAssoc(array $array, bool $strict = false): bool
@@ -772,7 +801,7 @@ public static function createMulti(array $keys, ?array $values = null): array
      * Make variable an array (according to flag settings)
      *
      * @param mixed $var
-     * @param int $flag Set flag(s) to preserve specific values from being converted to array
+     * @param int $flag Set flag(s) to preserve specific values from being converted to array (see Arr::FORCE_ARRAY_ constants)
      * @return array
      */
     public static function forceArray($var, int $flag = self::FORCE_ARRAY_ALL)

test/ArrTest.php

@@ -120,24 +120,70 @@ public function testUnpack()
                     'key3' => ['test', 'test2'],
                     'key4' => 'test3'
                 ],
-                1
+                1 => ['a' => 'b', 'c'],
             ],
-            2,
+            2 => [3 => 4, 5 => 6],
             4 => 56
         ];
         $array2 = [1, 2, 3, 4, 5];
 
+
+        // Test default mode
         $this->assertSame([
             'key1.key2.key3.0' => 'test',
             'key1.key2.key3.1' => 'test2',
             'key1.key2.key4' => 'test3',
-            'key1.0' => 1,
-            0 => 2,
+            'key1.1.a' => 'b',
+            'key1.1.0' => 'c',
+            '2.3' => 4,
+            '2.5' => 6,
             4 => 56,
 
         ], Arr::unpack($array));
 
         $this->assertSame($array2, Arr::unpack($array2));
+
+
+        // Test UNPACK_PRESERVE_LIST_ARRAY mode
+        $this->assertSame([
+            'key1.key2.key3' => ['test', 'test2'],
+            'key1.key2.key4' => 'test3',
+            'key1.1.a' => 'b',
+            'key1.1.0' => 'c',
+            '2.3' => 4,
+            '2.5' => 6,
+            4 => 56,
+
+        ], Arr::unpack($array, Arr::UNPACK_PRESERVE_LIST_ARRAY));
+
+        $this->assertSame($array2, Arr::unpack($array2, Arr::UNPACK_PRESERVE_LIST_ARRAY));
+
+
+        // Test UNPACK_PRESERVE_ASSOC_ARRAY mode
+        $this->assertSame([
+            'key1.key2.key3.0' => 'test',
+            'key1.key2.key3.1' => 'test2',
+            'key1.key2.key4' => 'test3',
+            'key1.1' => ['a' => 'b', 0 => 'c'],
+            2 => [3 => 4, 5 => 6],
+            4 => 56,
+
+        ], Arr::unpack($array, Arr::UNPACK_PRESERVE_ASSOC_ARRAY));
+
+        $this->assertSame($array2, Arr::unpack($array2, Arr::UNPACK_PRESERVE_ASSOC_ARRAY));
+
+
+        // Test UNPACK_PRESERVE_ARRAY mode
+        $this->assertSame([
+            'key1.key2.key3' => ['test', 'test2'],
+            'key1.key2.key4' => 'test3',
+            'key1.1' => ['a' => 'b', 0 => 'c'],
+            2 => [3 => 4, 5 => 6],
+            4 => 56,
+
+        ], Arr::unpack($array, Arr::UNPACK_PRESERVE_ARRAY));
+
+        $this->assertSame($array2, Arr::unpack($array2, Arr::UNPACK_PRESERVE_ARRAY));
     }
 
     /********************************* Validation *********************************/