README

此库实现了符合RFC6901规范的JSON指针。

要求

• PHP 8.1

功能

• 选择JSON文档的一部分。
• 删除JSON文档的一部分。
• 替换/添加JSON文档的一部分。

安装

您需要composer来完成安装。

composer require remorhaz/php-json-pointer

文档

访问JSON文档

您可以使用相应的节点值工厂从编码的JSON字符串或解码的JSON数据创建可访问的JSON文档。

<?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);

创建查询

您应该使用查询工厂从JSON指针表达式创建查询。

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

$queryFactory = QueryFactory::create();

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

处理查询

您应该使用一个查询处理器的实例来执行给定JSON文档上的查询。

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

$processor = Processor::create();

选择JSON文档的一部分

要获取JSON文档的一部分，请使用::select()方法。

<?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

注意，您可以将选择结果编码为JSON字符串或将它们解码为原始PHP数据。在访问::select()的结果之前，您可以使用::exists()方法检查其存在性以避免异常。

删除JSON文档的一部分

要删除JSON文档的一部分，请使用::delete()方法。

<?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

注意，如果查询指向不存在的值，::delete()函数将返回不存在的结果。

替换JSON文档的一部分

要替换JSON文档的一部分，请使用::replace()方法。

<?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

添加JSON文档的一部分

要添加JSON文档的一部分，请使用::add()方法。

<?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]'

如果查询指向现有属性，它将被替换。注意，您只能向现有对象/数组添加值。

许可

PHP JSON Pointer采用MIT许可。