devlop/json

Simple JSON wrapper for better experience working with json data

1.3.2 2021-10-13 17:52 UTC

Requires

• php: ^7.4|^8.0

Requires (Dev)

• devlop/phpunit-exception-assertions: ^1.0
• phpunit/phpunit: ^9.5
• symfony/polyfill-php81: ^1.22
• symfony/var-dumper: ^5.2

MIT

• Johan Rosenson

README

Json

JSON wrapper that provide better developer experience than the native json_encode and json_decode.

Installation

composer require devlop/json

Differences to json_encode / json_decode

• Always throws \JsonException on errors
• Consistent order of arguments ($value/$json, $flags, $depth)
• Stricter when encoding and decoding, only supports arrays and objects, does not support scalar values

Usage

Both encode and decode are static methods and have the same order of arguments: first the input, followed by int $flags and lastly int $depth.

Encoding

The encode method is a wrapper for the native json_encode method.

Signature: public static function encode(array|object $value, int $flags = 0, int $depth = 512) : string

use Devlop\Json\Json;

$output = Json::encode($input);

// or with flags
$output = Json::encode($input, \JSON_HEX_TAG | \JSON_NUMERIC_CHECK);

Encoding (Pretty Print)

The pretty method is a convenience method to get pretty formatted output without having to manually specify the JSON_PRETTY_PRINT flag.

It has the same signature as encode().

use Devlop\Json\Json;

$output = Json::pretty($input);

// or with flags
$output = Json::encode($input, \JSON_HEX_TAG | \JSON_NUMERIC_CHECK);

Decoding

The decode method is a wrapper for the native json_decode method.

Signature: public static function decode(string $json, int $flags = 0, int $depth = 512) : array|object

use Devlop\Json\Json;

$output = Json::decode($input);

// or with flags
$output = Json::decode($input, \JSON_INVALID_UTF8_IGNORE);

Decoding (Associative)

The decodeAssoc method is a convenience method to decode but force all objects to associative arrays without having to manually specify the JSON_OBJECT_AS_ARRAY flag.

It has the same signature as decode().

use Devlop\Json\Json;

$output = Json::decodeAssoc($input);

// or with flags
$output = Json::decodeAssoc($input, \JSON_INVALID_UTF8_IGNORE);

Error handling

Any time an error occurs the native JsonException will be thrown.

Supported types

My belief is that the most common usage of JSON in PHP is to store a JSON representation of arrays or objects. It is true that a single string, integer, boolean or even a single null value is a valid JSON document, but if you are as me and only using JSON for arrays or objects then it's just easier to treat anything else as invalid data and throw an exception, this removes some of the need to check the type after decoding.

depth argument and NO_FLAGS

If you want to access the $depth argument without adding any additional flags, you must supply the default value 0 for the $flags argument, but to make the experiance more clearer you can use the constant Json::NO_FLAGS instead.

$output = Json::encode($input, Json::NO_FLAGS, 3);