remorhaz / php-json-pointer
JSON Pointer (RFC-6901) PHP implementation
Installs: 425 389
Dependents: 2
Suggesters: 0
Security: 0
Stars: 5
Watchers: 2
Forks: 2
Open Issues: 0
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)
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.