Add support for escaping delimiter while parsing path

CHANGELOG.md

@@ -3,20 +3,21 @@
 
 ## 2.0.1 under development
 
-- no changes in this release.
+- Enh #111: Add support for escaping delimiter while parsing path (@arogachev)
+- New #111: Add `ArrayHelper::parsePath()` method (@arogachev)
 
 ## 2.0.0 October 23, 2021
 
-- New #91: Add `ArrayHelper::group()` that groups the array according to a specified key (sagittaracc)
+- New #91: Add `ArrayHelper::group()` that groups the array according to a specified key (@sagittaracc)
 - New #96: Add support for iterable objects to `ArrayHelper::map()`, `ArrayHelper::index()`, `ArrayHelper::group()`,
-  `ArrayHelper::htmlEncode()` and `ArrayHelper::htmlDecode` (vjik)
-- Chg #99: Finalize `ArrayHelper` and `ArraySorter` (vjik)
+  `ArrayHelper::htmlEncode()` and `ArrayHelper::htmlDecode` (@vjik)
+- Chg #99: Finalize `ArrayHelper` and `ArraySorter` (@vjik)
 - Bug #101: Fix incorrect default value returned from `ArrayHelper::getValue()` when key does not exist and
-  default is array (vjik)
+  default is array (@vjik)
 
 ## 1.0.1 February 10, 2021
 
-- Chg: Update yiisoft/strings dependency (samdark)
+- Chg: Update yiisoft/strings dependency (@samdark)
 
 ## 1.0.0 February 02, 2021
 

src/ArrayHelper.php

@@ -19,6 +19,9 @@
 use function is_int;
 use function is_object;
 use function is_string;
+use function sprintf;
+use function str_replace;
+use function strlen;
 
 /**
  * Yii array helper provides static methods allowing you to deal with arrays more efficiently.
@@ -428,21 +431,27 @@ public static function setValueByPath(array &$array, $path, $value, string $deli
 
     /**
      * @param array|float|int|string $path The path of where do you want to write a value to `$array`.
-     * The path can be described by a string when each key should be separated by delimiter.
+     * The path can be described by a string when each key should be separated by delimiter. If a path item contains
+     * delimiter, it can be escaped with "\" (backslash) or a custom delimiter can be used.
      * You can also describe the path as an array of keys.
-     * @param string $delimiter A separator, used to parse string $key for embedded object property retrieving. Defaults
+     * @param string $delimiter A separator, used to parse string key for embedded object property retrieving. Defaults
      * to "." (dot).
+     * @param string $escapeCharacter An escape character, used to escape delimiter. Defaults to "\" (backslash).
+     * @param bool $preserveDelimiterEscaping Whether to preserve delimiter escaping in the items of final array (in
+     * case of using string as an input). When `false`, "\" (backslashes) are removed. For a "." as delimiter, "."
+     * becomes "\.". Defaults to `false`.
      *
      * @psalm-param ArrayPath $path
      *
      * @return array|float|int|string
      * @psalm-return ArrayKey
      */
-    private static function parsePath($path, string $delimiter)
-    {
-        if (is_string($path)) {
-            return explode($delimiter, $path);
-        }
+    public static function parsePath(
+        $path,
+        string $delimiter = '.',
+        string $escapeCharacter = '\\',
+        bool $preserveDelimiterEscaping = false
+    ) {
         if (is_array($path)) {
             $newPath = [];
             foreach ($path as $key) {
@@ -456,7 +465,41 @@ private static function parsePath($path, string $delimiter)
             }
             return $newPath;
         }
-        return $path;
+
+        if (!is_string($path)) {
+            return $path;
+        }
+
+        if (strlen($delimiter) !== 1) {
+            throw new InvalidArgumentException('Only 1 character is allowed for delimiter.');
+        }
+
+        if (strlen($escapeCharacter) !== 1) {
+            throw new InvalidArgumentException('Only 1 escape character is allowed.');
+        }
+
+        if ($delimiter === $escapeCharacter) {
+            throw new InvalidArgumentException('Delimiter and escape character must be different.');
+        }
+
+        if (($path[0] ?? '') === $delimiter) {
+            throw new InvalidArgumentException('Delimiter can\'t be at the very beginning.');
+        }
+
+        if (substr($path, -1) === $delimiter && substr($path, -2) !== '\\' . $delimiter) {
+            throw new InvalidArgumentException('Delimiter can\'t be at the very end.');
+        }
+
+        $pattern = sprintf('/(?<!\\%s)\%s/', $escapeCharacter, $delimiter);
+        $matches = preg_split($pattern, $path);
+
+        if ($preserveDelimiterEscaping === true) {
+            return $matches;
+        }
+
+        return array_map(static function (string $key) use ($delimiter, $escapeCharacter): string {
+            return str_replace($escapeCharacter . $delimiter, $delimiter, $key);
+        }, $matches);
     }
 
     /**

tests/ArrayHelper/ArrayHelperTest.php

@@ -119,7 +119,7 @@ public function testIsSubset(): void
         $this->assertFalse(ArrayHelper::isSubset(new ArrayObject([1]), ['1', 'b'], true));
     }
 
-    public function testGetObjectVars()
+    public function testGetObjectVars(): void
     {
         $this->assertSame([
             'id' => 123,

tests/ArrayHelper/GetValueByPathTest.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArrayHelper;
+
+use PHPUnit\Framework\TestCase;
+use Yiisoft\Arrays\ArrayHelper;
+
+final class GetValueByPathTest extends TestCase
+{
+    public function getValueByPathDataProvider(): array
+    {
+        return [
+            [['key1' => ['key2' => ['key3' => 'value']]], 'key1.key2.key3', '.', 'value'],
+            [['key1.key2' => ['key3' => 'value']], 'key1.key2.key3', '.', null],
+            [['key1.key2' => ['key3' => 'value']], 'key1\.key2.key3', '.', 'value'],
+            [['key1:key2' => ['key3' => 'value']], 'key1\:key2:key3', ':', 'value'],
+        ];
+    }
+
+    /**
+     * @dataProvider getValueByPathDataProvider
+     */
+    public function testGetValueByPath(array $array, string $path, string $delimiter, ?string $expectedValue): void
+    {
+        $this->assertSame($expectedValue, ArrayHelper::getValueByPath($array, $path, null, $delimiter));
+    }
+}

tests/ArrayHelper/ParsePathTest.php

@@ -0,0 +1,87 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArrayHelper;
+
+use InvalidArgumentException;
+use PHPUnit\Framework\TestCase;
+use Yiisoft\Arrays\ArrayHelper;
+
+final class ParsePathTest extends TestCase
+{
+    public function parsePathDataProvider(): array
+    {
+        return [
+            ['key1.key2.key3', '.', '\\', false, ['key1', 'key2', 'key3']],
+            ['key1..key2..key3', '.', '\\', false, ['key1', '', 'key2', '', 'key3']],
+            ['key1...key2...key3', '.', '\\', false, ['key1', '', '', 'key2', '', '', 'key3']],
+            ['key1\.key2.key3', '.', '\\', false, ['key1.key2', 'key3']],
+            ['\.key1.key2', '.', '\\', false, ['.key1', 'key2']],
+            ['key1.key2\.', '.', '\\', false, ['key1', 'key2.']],
+            ['key1\..\.key2\..\.key3', '.', '\\', false, ['key1.', '.key2.', '.key3']],
+            ['key1\\\.', '.', '\\', false, ['key1\.']],
+
+            ['key1\:key2:key3', ':', '\\', false, ['key1:key2', 'key3']],
+
+            ['key1\.key2.key3', '.', '\\', true, ['key1\.key2', 'key3']],
+
+            ['key1\\key2\\key3', '\\', '/', false, ['key1', 'key2', 'key3']],
+            ['key1\\\\key2\\\\key3', '\\', '/', false, ['key1', '', 'key2', '', 'key3']],
+            ['key1\\\\\\key2\\\\\\key3', '\\', '/', false, ['key1', '', '', 'key2', '', '', 'key3']],
+            ['key1/\\\\/\key2/\\\\/\key3', '\\', '/', false, ['key1\\', '\\key2\\', '\\key3']],
+        ];
+    }
+
+    /**
+     * @dataProvider parsePathDataProvider
+     */
+    public function testParsePath(
+        string $path,
+        string $delimiter,
+        string $escapeCharacter,
+        bool $preserveDelimiterEscaping,
+        array $expectedPath
+    ): void {
+        $actualPath = ArrayHelper::parsePath($path, $delimiter, $escapeCharacter, $preserveDelimiterEscaping);
+        $this->assertSame($expectedPath, $actualPath);
+    }
+
+    public function testParsePathWithLongDelimiter(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Only 1 character is allowed for delimiter.');
+
+        ArrayHelper::parsePath('key1..key2.key3', '..');
+    }
+
+    public function testParsePathWithLongEscapeCharacter(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Only 1 escape character is allowed.');
+
+        ArrayHelper::parsePath('key1.key2.key3', '.', '//');
+    }
+
+    public function testParsePathWithDelimiterEqualsEscapeCharacter(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Delimiter and escape character must be different.');
+
+        ArrayHelper::parsePath('key1.key2.key3', '.', '.');
+    }
+
+    public function testParsePathWithDelimiterAtBeginning(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Delimiter can\'t be at the very beginning.');
+        ArrayHelper::parsePath('.key1.key2');
+    }
+
+    public function testParsePathWithDelimiterAtEnd(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Delimiter can\'t be at the very end.');
+        ArrayHelper::parsePath('key1.key2.');
+    }
+}