devlop / json
Simple JSON wrapper for better experience working with json data
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
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);