stratadox / json
Requires
- php: >=7.2
Requires (Dev)
- fzaninotto/faker: ^1.7
- php-coveralls/php-coveralls: ^2.0
- phpstan/phpstan: ^0.9.2
- phpunit/phpunit: ^7.3
This package is auto-updated.
Last update: 2024-10-29 05:28:31 UTC
README
Json handling library for easily reading from and writing to json strings.
Installation
Install with composer require stratadox/json
What is this?
This library provides a simple object-oriented way of dealing with json strings in php.
The basic idea is to create a Json
(php) object from either a json string or
"raw" data, which represents the json data in the php world.
Through this object, the contents of the json data can be retrieved. The
interface also provides a mechanism for altering the json structure, either by
modifying the current instance or by returning a modified copy.
To produce a json-encoded text representation of the contents, simply casting the Json instance to string is enough.
How to use this?
The package provides two approaches to handling json structures: an immutable
and a mutable way.
They both implement the same interface and differ only in the way they implement
the write
method.
Immutable Json
Create an immutable json structure by converting a json-encoded string:
<?php use Stratadox\Json\ImmutableJson; $json = ImmutableJson::fromString('{"foo":{"bar":"baz"}}');
Or from the "raw" data:
<?php use Stratadox\Json\ImmutableJson; $json = ImmutableJson::fromData(['foo' => ['bar' => 'baz']]);
Retrieve the values:
assert(['bar' => 'baz'] === $json->retrieve('foo'));
Retrieve nested values:
assert('baz' === $json->retrieve('foo', 'bar'));
Write values to a new copy:
$changed = $json->write('qux', 'foo', 'bar');
(Notice that the value to be written comes before the path.)
The changed structure will contain the new value:
assert('{"foo":{"bar":"qux"}}' === (string) $changed);
The original structure will not be modified:
assert('{"foo":{"bar":"baz"}}' === (string) $json);
The write-calls can be chained:
$changed = $json ->write('qux', 'foo', 'bar') ->write(123, 'foo', 'baz'); assert('{"foo":{"bar":"qux","baz":123}}' === (string) $changed);
Mutable Json
Create a mutable json structure by converting a json-encoded string:
<?php use Stratadox\Json\MutableJson; $json = MutableJson::fromString('{"foo":{"bar":"baz"}}');
Or from the "raw" data:
<?php use Stratadox\Json\MutableJson; $json = MutableJson::fromData(['foo' => ['bar' => 'baz']]);
Retrieve the values:
assert(['bar' => 'baz'] === $json->retrieve('foo'));
Retrieve nested values:
assert('baz' === $json->retrieve('foo', 'bar'));
Write new values to the structure:
$json->write('qux', 'foo', 'bar');
(Notice that the value to be written comes before the path.)
The write-calls can be chained:
$json ->write('qux', 'foo', 'bar') ->write(123, 'foo', 'baz'); assert('{"foo":{"bar":"qux","baz":123}}' === (string) $json);
Parser
The JsonParser is a simple factory to create either mutable or immutable Json instances from string.
<?php use Stratadox\Json\JsonParser; $json = JsonParser::create()->from('{"foo":{"bar":"baz"}}');
It can be used in cases where you need to parse strings, but don't want to call the constructors directly.
<?php namespace Acme; use Stratadox\Json\Json; use Stratadox\Json\Parser; class Signer { private $parseJson; private $signatureName; public function __construct(Parser $jsonParser, string $name) { $this->parseJson = $jsonParser; $this->signatureName = $name; } public function addSignatureTo(string $input): string { return (string) $this->sign($this->parseJson->from($input)); } private function sign(Json $input): Json { return $input->write($this->signatureName, 'Signed', 'by'); } }
By default, the parser produces immutable json instances. It can be tuned to
produce mutable instances instead, by using the mutable
method. To turn it
back to immutable, use the immutable
method.
Fun fact: the JsonParser currently allows exactly two instances of its class, making it an implementation of the little-known Doubleton pattern.