Add initial version

Author: slavcodev

src/InvalidArgumentException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Slavcodev\JsonPointer;
+
+use InvalidArgumentException as PhpInvalidArgumentException;
+use Throwable;
+
+final class InvalidArgumentException extends PhpInvalidArgumentException implements JsonPointerException
+{
+    public function __construct(string $message, Throwable $previous = null)
+    {
+        parent::__construct($message, 0, $previous);
+    }
+}

src/JsonPointer.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Slavcodev\JsonPointer;
+
+use function explode;
+use function mb_substr;
+use function preg_match;
+use function strtr;
+
+/**
+ * The object implementation of the JSON pointer
+ *
+ * Rules:
+ *
+ * - A JSON Pointer is a Unicode string (see [RFC4627], Section 3) containing a sequence of zero or more reference tokens,
+ *   each prefixed by a '/' (%x2F) character;
+ * - Each reference token contains zero or more Unicode characters: %x00-10FFFF (except special chars `%x2F` and `%x7E`);
+ * - Characters `~` and `/` are encoded in reference token into `~0` and `~1` respectively;
+ *
+ * @see https://tools.ietf.org/html/rfc6901
+ *
+ * @psalm-immutable
+ */
+final class JsonPointer
+{
+    private const SPECIAL_CASES = ['~1' => '/', '~0' => '~'];
+
+    public string $value;
+
+    public bool $anchored = false;
+
+    public array $tokens = [];
+
+    /**
+     * @throws InvalidArgumentException if passed string is invalid JSON pointer.
+     */
+    public function __construct(string $value = '')
+    {
+        $this->value = $value;
+
+        // If URI fragment representation, strip `#`.
+        if (!empty($value) && $value[0] === '#') {
+            $value = mb_substr($value, 1);
+            $this->anchored = true;
+        }
+
+        if (!empty($value)) {
+            if ($value[0] !== '/') {
+                throw new InvalidArgumentException('Invalid JSON pointer syntax');
+            }
+
+            foreach (explode('/', mb_substr($value, 1)) as $key) {
+                if (preg_match('/~[^0-1]/', $key)) {
+                    throw new InvalidArgumentException('Invalid JSON pointer syntax');
+                }
+
+                $this->tokens[] = strtr($key, self::SPECIAL_CASES);
+            }
+        }
+    }
+
+    public function __toString(): string
+    {
+        return $this->toString();
+    }
+
+    public function toString(): string
+    {
+        return $this->value;
+    }
+}

src/JsonPointerException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Slavcodev\JsonPointer;
+
+interface JsonPointerException
+{
+}

tests/JsonPointerTest.php

@@ -0,0 +1,90 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Slavcodev\JsonPointer\Tests;
+
+use Slavcodev\JsonPointer\InvalidArgumentException;
+use Slavcodev\JsonPointer\JsonPointer;
+use function array_shift;
+
+final class JsonPointerTest extends TestCase
+{
+    /**
+     * @test
+     * @dataProvider provideInvalidJsonPointers
+     */
+    public function validatesValueOnConstruct(string $value): void
+    {
+        $this->expectExceptionObject(new InvalidArgumentException('Invalid JSON pointer syntax'));
+        new JsonPointer($value);
+    }
+
+    public function provideInvalidJsonPointers(): iterable
+    {
+        return [
+            'must start with token prefix' => ['foo'],
+            'must start with `#` representing URI fragment' => ['#foo'],
+            'must start with token prefix or `#`' => [' /'],
+            'must not contain unescaped `~`' => ['/~foo'],
+        ];
+    }
+
+    /**
+     * @test
+     * @dataProvider provideJsonPointersAndUriFragments
+     */
+    public function isInstantiatedFromString(string $value, array $expectedTokens, bool $anchored): void
+    {
+        $pointer = new JsonPointer($value);
+        self::assertSame($value, $pointer->toString());
+        self::assertSame($value, (string) $pointer);
+        self::assertSame($expectedTokens, $pointer->tokens);
+        self::assertSame($anchored, $pointer->anchored);
+    }
+
+    /**
+     * @test
+     */
+    public function isInstantiatedWithDefaultValue(): void
+    {
+        $pointer = new JsonPointer();
+        self::assertSame('', $pointer->toString());
+        self::assertSame('', (string) $pointer);
+        self::assertSame([], $pointer->tokens);
+        self::assertFalse($pointer->anchored);
+    }
+
+    public function provideJsonPointers(): iterable
+    {
+        return [
+            'basic' => ['/foo', ['foo']],
+            'basic (1)' => ['/foo/bar', ['foo', 'bar']],
+            'empty' => ['', []],
+            'empty token' => ['/', ['']],
+            'empty tokens' => ['//', ['', '']],
+            'token with space' => ['/ ', [' ']],
+            'token with `%`' => ['/f%o', ['f%o']],
+            'token with `^`' => ['/f^o', ['f^o']],
+            'token with `|`' => ['/f|o', ['f|o']],
+            'token with `\\`' => ['/f\\o', ['f\\o']],
+            'token with `\'`' => ['/f\'o', ['f\'o']],
+            'token with NUL (Unicode U+0000)' => ["/f\0o", ["f\0o"]],
+            'token with `"`' => ['/f"o', ['f"o']],
+            'token with `/`' => ['/~1foo/bar~1/baz', ['/foo', 'bar/', 'baz']],
+            'token with `/` (1)' => ['/f~1o', ['f/o']],
+            'token with `~`' => ['/~0foo/bar~0/baz', ['~foo', 'bar~', 'baz']],
+            'token with `~` (1)' => ['/f~0o', ['f~o']],
+            'numeric token' => ['/foo/0', ['foo', '0']],
+        ];
+    }
+
+    public function provideJsonPointersAndUriFragments(): iterable
+    {
+        foreach ($this->provideJsonPointers() as $key => $set) {
+            $value = array_shift($set);
+            yield "{$key} - {$value}" => [$value, ...$set, false];
+            yield "{$key} - #{$value}" => ["#{$value}", ...$set, true];
+        }
+    }
+}

tests/TestCase.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Slavcodev\JsonPointer\Tests;
+
+use PHPUnit\Framework;
+
+abstract class TestCase extends Framework\TestCase
+{
+}