remorhaz/php-json-pointer

JSON Pointer (RFC-6901) PHP implementation

v0.7.1 2024-02-19 22:34 UTC

Requires

• php: ~8.1.0 || ~8.2.0 || ~8.3.0
• remorhaz/php-json-data: ^0.7
• remorhaz/php-unilex: ^0.5.3

Requires (Dev)

• bamarni/composer-bin-plugin: ^1.8
• phpunit/phpunit: ^10.1 || ^11

Suggests

• remorhaz/php-json-patch: Uses JSON Pointers to implement the declarative way of altering JSON data (RFC-6902)

MIT

• Edward Surov

• json
• json pointer
• RFC6901
• rfc-6901

README

This library implements RFC6901-compliant JSON pointers.

Requirements

• PHP 8.1

Features

• Selecting part of a JSON document.
• Removing part of a JSON document.
• Replacing/adding part of a JSON document.

Installation

You will need composer to perform install.

composer require remorhaz/php-json-pointer

Documentation

Accessing JSON document

You can create accessible JSON document either from encoded JSON string or from decoded JSON data using corresponding node value factory:

<?php
use Remorhaz\JSON\Data\Value\EncodedJson;
use Remorhaz\JSON\Data\Value\DecodedJson;

// Creating document from JSON-encoded string:
$encodedValueFactory = EncodedJson\NodeValueFactory::create();
$encodedJson = '{"a":1}';
$document1 = $encodedValueFactory->createValue($encodedJson);

// Creating document from decoded JSON data:
$decodedValueFactory = DecodedJson\NodeValueFactory::create();
$decodedJson = (object) ['a' => 1];
$document2 = $decodedValueFactory->createValue($decodedJson);

Creating query

You should use query factory to create query from JSON Pointer expression:

<?php
use Remorhaz\JSON\Pointer\Query\QueryFactory;

$queryFactory = QueryFactory::create();

// Creating query that selects 'a' property from document:
$query = $queryFactory->createQuery('/a');

Processing query

You should use an instance of query processor to execute queries on given JSON documents:

<?php
use Remorhaz\JSON\Pointer\Processor\Processor;

$processor = Processor::create();

Selecting part of a JSON document

To get part of a JSON document use ::select() method.

<?php
use Remorhaz\JSON\Data\Value\EncodedJson\NodeValueFactory;
use Remorhaz\JSON\Pointer\Processor\Processor;
use Remorhaz\JSON\Pointer\Query\QueryFactory;

$nodeValueFactory = NodeValueFactory::create();
$queryFactory = QueryFactory::create();
$processor = Processor::create();

$document = $nodeValueFactory->createValue('{"a":"b"}');

// Selecting existing value
$query1 = $queryFactory->createQuery('/a');
$result1 = $processor->select($query1, $document);
var_dump($result1->exists()); // boolean: true
var_dump($result1->decode()); // string: 'b'
var_dump($result1->encode()); // string: '"b"'

// Attempting to select non-existing value
$query2 = $queryFactory->createQuery('/c');
$result2 = $processor->select($query2, $document);
var_dump($result2->exists()); // boolean: false
var_dump($result2->decode()); // throws an exception

Note that you can either encode result of a selection to JSON string or decode them to raw PHP data. Before accessing a result of ::select() you can check it's existence with ::exists() method to avoid exception.

Deleting part of a JSON document

To delete part of a JSON document use ::delete() method.

<?php
use Remorhaz\JSON\Data\Value\EncodedJson\NodeValueFactory;
use Remorhaz\JSON\Pointer\Processor\Processor;
use Remorhaz\JSON\Pointer\Query\QueryFactory;

$nodeValueFactory = NodeValueFactory::create();
$queryFactory = QueryFactory::create();
$processor = Processor::create();

$document = $nodeValueFactory->createValue('{"a":"b","c":"d"}');

// Deleting existing value
$query1 = $queryFactory->createQuery('/a');
$result1 = $processor->delete($query1, $document);
var_dump($result1->exists()); // boolean: true
var_dump($result1->encode()); // string: '{"c":"d"}'

// Attempting to delete non-existing value
$query2 = $queryFactory->createQuery('/e');
$result2 = $processor->delete($query2, $document);
var_dump($result2->exists()); // boolean: false
var_dump($result2->encode()); // throws an exception

Note that ::delete() function returns non-existing result if query points to non-existing value.

Replacing part of a JSON document

To replace part of a JSON document use ::replace() method.

<?php
use Remorhaz\JSON\Data\Value\EncodedJson\NodeValueFactory;
use Remorhaz\JSON\Pointer\Processor\Processor;
use Remorhaz\JSON\Pointer\Query\QueryFactory;

$nodeValueFactory = NodeValueFactory::create();
$queryFactory = QueryFactory::create();
$processor = Processor::create();

$document = $nodeValueFactory->createValue('{"a":"b","c":"d"}');
$replacement = $nodeValueFactory->createValue('"e"');

// Replacing existing value
$query1 = $queryFactory->createQuery('/a');
$result1 = $processor->replace($query1, $document, $replacement);
var_dump($result1->exists()); // boolean: true
var_dump($result1->encode()); // string: '{"a":"e","c":"d"}'

// Attempting to replace non-existing value
$query2 = $queryFactory->createQuery('/f');
$result2 = $processor->replace($query2, $document, $replacement);
var_dump($result2->exists()); // boolean: false
var_dump($result2->encode()); // throws an exception

Adding part of a JSON document

To add part of a JSON document use ::add() method.

<?php
use Remorhaz\JSON\Data\Value\EncodedJson\NodeValueFactory;
use Remorhaz\JSON\Pointer\Processor\Processor;
use Remorhaz\JSON\Pointer\Query\QueryFactory;

$nodeValueFactory = NodeValueFactory::create();
$queryFactory = QueryFactory::create();
$processor = Processor::create();

// Working with object
$document1 = $nodeValueFactory->createValue('{"a":"b","c":"d"}');
$replacement1 = $nodeValueFactory->createValue('"e"');

// Replacing existing property
$query1 = $queryFactory->createQuery('/a');
$result1 = $processor->add($query1, $document1, $replacement1);
var_dump($result1->exists()); // boolean: true
var_dump($result1->encode()); // string: '{"a":"e","c":"d"}'

// Adding non-existing property
$query2 = $queryFactory->createQuery('/f');
$result2 = $processor->add($query2, $document1, $replacement1);
var_dump($result2->exists()); // boolean: true
var_dump($result2->encode()); // string: '{"a":"b","c":"d","f":"e"}'

// Adding non-existing property
$query2 = $queryFactory->createQuery('/f');
$result2 = $processor->add($query2, $document1, $replacement1);
var_dump($result2->exists()); // boolean: true
var_dump($result2->encode()); // string: '{"a":"b","c":"d","f":"e"}'

// Attempting to add property to non-existing object
$query3 = $queryFactory->createQuery('/e/f');
$result3 = $processor->add($query3, $document1, $replacement1);
var_dump($result3->exists()); // boolean: false
var_dump($result3->encode()); // throws an exception

// Working with array
$document2 = $nodeValueFactory->createValue('[1,2]');
$replacement2 = $nodeValueFactory->createValue('3');

// Inserting new element before given index
$query4 = $queryFactory->createQuery('/1');
$result4 = $processor->add($query4, $document2, $replacement2);
var_dump($result4->exists()); // boolean: true
var_dump($result4->encode()); // string: '[1,3,2]'

// Appending new element to the end of array
$query5 = $queryFactory->createQuery('/-');
$result5 = $processor->add($query5, $document2, $replacement2);
var_dump($result5->exists()); // boolean: true
var_dump($result5->encode()); // string: '[1,2,3]'

If query points to existing property it will be replaced. Note that you can add values only to existing objects/arrays.

License

PHP JSON Pointer is licensed under MIT license.