ergebnis/json-pointer

Provides JSON pointer as a value object.

3.2.0 2022-11-28 17:03 UTC

Requires

• php: ^8.0

Requires (Dev)

• ergebnis/composer-normalize: ^2.28.3
• ergebnis/data-provider: ^1.2.0
• ergebnis/license: ^2.1.0
• ergebnis/php-cs-fixer-config: ^5.0.0
• fakerphp/faker: ^1.20.0
• infection/infection: ~0.26.16
• phpunit/phpunit: ^9.5.26
• psalm/plugin-phpunit: ~0.18.3
• vimeo/psalm: ^4.30

MIT

• Andreas Möller

• json
• pointer
• RFC6901

README

Provides JSON pointer as a value object.

Installation

Run

composer require ergebnis/json-pointer

Usage

ReferenceToken

You can create a ReferenceToken from a string value:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$referenceToken = Pointer\ReferenceToken::fromString('foo/9000/😆');

$referenceToken->toJsonString();                  // 'foo~19000~😆'
$referenceToken->toString();                      // 'foo/9000/😆'
$referenceToken->toUriFragmentIdentifierString(); // 'foo~19000~1%F0%9F%98%86'

You can create a ReferenceToken from a JSON string value:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$referenceToken = Pointer\ReferenceToken::fromJsonString('foo~19000~😆');

$referenceToken->toJsonString();                  // 'foo~19000~😆'
$referenceToken->toString();                      // 'foo/9000/😆'
$referenceToken->toUriFragmentIdentifierString(); // 'foo~19000~1%F0%9F%98%86'

You can create a ReferenceToken from a URI fragment identifier string value:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$referenceToken = Pointer\ReferenceToken::fromUriFragmentIdentifierString('foo~19000~1%F0%9F%98%86');

$referenceToken->toJsonString();                  // 'foo~19000~😆'
$referenceToken->toString();                      // 'foo/9000/😆'
$referenceToken->toUriFragmentIdentifierString(); // 'foo~19000~1%F0%9F%98%86'

You can create a ReferenceToken from an int value:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$referenceToken = Pointer\ReferenceToken::fromInt(9001);

$referenceToken->toJsonString();                  // '9001'
$referenceToken->toString();                      // '9001'
$referenceToken->toUriFragmentIdentifierString(); // '9001'

You can compare ReferenceTokens:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$one = Pointer\ReferenceToken::fromString('foo/bar');
$two = Pointer\ReferenceToken::fromJsonString('foo~1bar');
$three = Pointer\ReferenceToken::fromString('foo/9000');

$one->equals($two);   // true
$one->equals($three); // false

JsonPointer

You can create a JsonPointer referencing a document:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$jsonPointer = Pointer\JsonPointer::document();

$jsonPointer->toJsonString();                  // ''
$jsonPointer->toUriFragmentIdentifierString(); // '#'

You can create a JsonPointer from a JSON string representation value:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$jsonPointer = Pointer\JsonPointer::fromJsonString('/foo/bar/😆');

$jsonPointer->toJsonString();                  // '/foo/bar/😆'
$jsonPointer->toUriFragmentIdentifierString(); // '#/foo/bar/%F0%9F%98%86'

You can create a JsonPointer from a URI fragment identifier string representation value:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$jsonPointer = Pointer\JsonPointer::fromUriFragmentIdentifierString('#/foo/bar/%F0%9F%98%86');

$jsonPointer->toJsonString();                  // '/foo/bar/😆'
$jsonPointer->toUriFragmentIdentifierString(); // '#/foo/bar/%F0%9F%98%86'

You can create a JsonPointer from ReferenceTokens:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$referenceTokens = [
    Pointer\ReferenceToken::fromString('foo'),
    Pointer\ReferenceToken::fromString('bar'),
];

$jsonPointer = Pointer\JsonPointer::fromReferenceTokens(...$referenceTokens);

$jsonPointer->toJsonString();                  // '/foo/bar'
$jsonPointer->toUriFragmentIdentifierString(); // '#/foo/bar'

You can compare JsonPointers:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$one = Pointer\JsonPointer::fromJsonString('/foo/bar');
$two = Pointer\JsonPointer::fromJsonString('/foo~1bar');
$three = Pointer\JsonPointer::fromUriFragmentIdentifierString('#/foo/bar');

$one->equals($two);   // false
$one->equals($three); // true

You can append a ReferenceToken to a JsonPointer:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$jsonPointer = Pointer\JsonPointer::fromJsonString('/foo/bar');

$referenceToken = Pointer\ReferenceToken::fromString('baz');

$newJsonPointer = $jsonPointer->append($referenceToken);

$newJsonPointer->toJsonString();                  // '/foo/bar/baz'
$newJsonPointer->toUriFragmentIdentifierString(); // '#foo/bar/baz'

Specification

You can create a Specification that is always satisfied by a JsonPointer:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$specification = Pointer\Specification::always();

$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo'));     // true
$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo/bar')); // true

You can create a Specification that is satisfied when a closure returns true for a JsonPointer:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$specification = Pointer\Specification::closure(static function (Pointer\JsonPointer $jsonPointer) {
    return $jsonPointer->toJsonString() === '/foo/bar';
});

$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo'));     // false
$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo/bar')); // true

You can create a Specification that is satisfied when a JsonPointer equals another JsonPointer:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$specification = Pointer\Specification::equals(Pointer\JsonPointer::fromJsonString('/foo/bar'));

$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo'));     // false
$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo/bar')); // true

You can create a Specification that is never satisfied by a JsonPointer:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$specification = Pointer\Specification::never();

$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo'));     // false
$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo/bar')); // false

You can create a Specification that is satisfied when another Specification is not satisfied by a JsonPointer:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$specification = Pointer\Specification::not(Pointer\Specification::equals(Pointer\JsonPointer::fromJsonString('/foo/bar')));

$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo'));     // true
$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo/bar')); // false

You can compose Specifications to find out if a JsonPointer satisfies any of them:

<?php

declare(strict_types=1);

use Ergebnis\Json\Pointer;

$specification = Pointer\Specification::anyOf(
    Pointer\Specification::closure(static function(Pointer\JsonPointer $jsonPointer) {
        return $jsonPointer->toJsonString() === '/foo/bar';
    }),
    Pointer\Specification::equals(Pointer\JsonPointer::fromJsonString('/foo/baz')),
    Pointer\Specification::never(),
);

$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo'));     // false
$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo/bar')); // true
$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo/baz')); // true

Changelog

Please have a look at CHANGELOG.md.

Contributing

Please have a look at CONTRIBUTING.md.

Code of Conduct

Please have a look at CODE_OF_CONDUCT.md.

License

This package is licensed using the MIT License.

Please have a look at LICENSE.md.

Curious what I am building?

📬 Subscribe to my list, and I will occasionally send you an email to let you know what I am working on.