suin/json

A Simple wrapper of json_decode() and json_encode(). This provides object-oriented interface and exception-based error handing.

1.2.0 2018-01-04 08:44 UTC

Requires

• php: >=7.1

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.9
• phpunit/phpunit: ^6.5
• suin/livexample: ^1.0
• suin/php-cs-fixer-rules: ^1.0

MIT

• suin

• json
• encoder
• exceptions
• wrapper
• decoder
• json_encode
• json_decode

README

Just a simple wrapper of json_decode() and json_encode(), but provides better interfaces: exception-based error handling and object oriented APIs.

Features

Compatible interface

This library provides the same interface with built-in functions, so you can replace your code easier.

Built-in function interface:

json_decode(
  string $json, 
  ?bool $assoc = false, 
  ?int $depth = 512, 
  ?int $options = 0
): mixed
json_encode(
  mixed $value, 
  ?int $options = 0,
  ?int $depth = 512 
): string

This library interface:

\Suin\Json\json_decode(
  string $json,
  ?bool $assoc = false,
  ?int $depth = 512,
  ?int $options = 0
): mixed
\Suin\Json\json_encode(
  mixed $value,
  ?int $options = 0,
  ?int $depth = 512
): string

\Suin\Json::decode(
  string $json,
  ?bool $assoc = false,
  ?int $depth = 512,
  ?int $options = 0
): mixed
\Suin\Json::encode(
  mixed $value,
  ?int $options = 0,
  ?int $depth = 512
): string

So that developers easily migrate to this library from the built-in functions. Just adding the following one line in the head of file:

use function Suin\Json\json_decode;
use function Suin\Json\json_encode;

For about the full migration example, see quick migration.

Exception-based error handling

• Throws DecodingException when failed to decode JSON.
• Throws EncodingException when failed to encode values.
• You don't have to treat json_last_error() any more.

// Error handling example
$json = "{'Organization': 'PHP Documentation Team'}";
try {
    Json::decode($json);
} catch (Json\DecodingException $e) {
    var_dump($e->getMessage());
    var_dump($e->getContext()->json());
}
// Output:
// string(35) "Failed to decode JSON: Syntax error"
// string(42) "{'Organization': 'PHP Documentation Team'}"

Object-oriented interface

As Decoder and Encoder class can be instantiated, you can re-use a preconfigured single decoder/encoder in several places.

// preconfigured decoder
$decoder = (new Decoder)->preferArray();
$array1 = $decoder->decode($json1);
$array2 = $decoder->decode($json2); // re-use it
$array3 = $decoder->decode($json3); // re-use it
  
// preconfigured encoder
$encoder = (new Encoder)->prettyPrint()->unescapeSlashes()->unescapeUnicode();
$json1 = $encoder->encode($value1);
$json2 = $encoder->encode($value2); // re-use it
$json3 = $encoder->encode($value3); // re-use it

Immutable Decoder object

As the Decoder object setting can not be changed once being instantiated, it is safer even in the case of sharing the object among some modules.

Installation via Composer

$ composer require suin/json

Example

Decoding JSON to values using Json class

<?php

use Suin\Json;

$json = '{"a":1,"b":2,"c":3,"d":4,"e":5}';
var_dump(Json::decode($json));
var_dump(Json::decode($json, true));
// Output:
// object(stdClass)#%d (5) {
//   ["a"]=>
//   int(1)
//   ["b"]=>
//   int(2)
//   ["c"]=>
//   int(3)
//   ["d"]=>
//   int(4)
//   ["e"]=>
//   int(5)
// }
// array(5) {
//   ["a"]=>
//   int(1)
//   ["b"]=>
//   int(2)
//   ["c"]=>
//   int(3)
//   ["d"]=>
//   int(4)
//   ["e"]=>
//   int(5)
// }

Encoding values to JSON using Json class

<?php

use Suin\Json;

$value = ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5];
var_dump(Json::encode($value));
// Output:
// string(31) "{"a":1,"b":2,"c":3,"d":4,"e":5}"

To see more examples, visit ./example folder.

Changelog

Please see CHANGELOG for more details.

Contributing

Please see CONTRIBUTING for more details.