README

A PHP library for JSON encoding and decoding with adapter-based extensibility.

Features

• Simple static shortcuts for common usage
• Instance-based usage with configurable defaults
• Validated context options
• Dedicated exceptions for encode/decode errors
• Helpers for decoding JSON specifically to array or object
• Adapter-based encoder and decoder architecture
• Automatic adapter selection based on available compatible simdjson_* functions
• Native PHP JSON fallback when no supported extension is available

Installation

composer require snortlin/json-codec

Requirements

• PHP 8.5 or higher
• Optional: compatible simdjson_* PHP functions

The simdjson extension is not required. If compatible simdjson_* functions are available, the library automatically selects the matching adapter. Otherwise, it falls back to PHP's native JSON functions.

This includes support for awesomized/simdjson-plus-php-ext, which provides simdjson_encode() and simdjson_decode() functions.

Basic usage

Encode data to JSON

use Snortlin\JsonCodec\JsonEncoder;

$json = JsonEncoder::toJson([
    'name' => 'John',
    'active' => true,
]);

Decode JSON to object

use Snortlin\JsonCodec\JsonDecoder;

$data = JsonDecoder::toObject('{"name":"John","active":true}');

echo $data->name; // John

Decode JSON to array

use Snortlin\JsonCodec\JsonDecoder;

$data = JsonDecoder::toArray('{"name":"John","active":true}');

echo $data['name']; // John

Context options

Encoding

use Snortlin\JsonCodec\JsonEncoder;

$json = JsonEncoder::toJson(
    ['name' => 'John'],
    [
        JsonEncoder::OPTIONS => JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES,
        JsonEncoder::RECURSION_DEPTH => 512,
    ],
);

Supported encoder context options:

• JsonEncoder::OPTIONS - JSON encoding flags
• JsonEncoder::RECURSION_DEPTH - maximum encoding depth, greater than zero

Decoding

use Snortlin\JsonCodec\JsonDecoder;

$data = JsonDecoder::toArray(
    '{"name":"John"}',
    [
        JsonDecoder::RECURSION_DEPTH => 512,
    ],
);

Supported decoder context options:

• JsonDecoder::ASSOCIATIVE - decode JSON objects as associative arrays when using decode()
• JsonDecoder::RECURSION_DEPTH - maximum decoding depth, greater than zero

Reusable encoder and decoder instances

Use instances when you want to configure default context options once and reuse them.

use Snortlin\JsonCodec\JsonEncoder;

$encoder = new JsonEncoder(defaultContext: [
    JsonEncoder::OPTIONS => JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES,
]);

$json = $encoder->encode([
    'name' => 'John',
]);

use Snortlin\JsonCodec\JsonDecoder;

$decoder = new JsonDecoder(defaultContext: [
    JsonDecoder::ASSOCIATIVE => true,
]);

$data = $decoder->decode('{"name":"John"}');

Exceptions

The library uses dedicated exception classes for invalid context values and JSON errors.

use Snortlin\JsonCodec\Exception\JsonDecodeException;
use Snortlin\JsonCodec\Exception\JsonUnexpectedTypeException;
use Snortlin\JsonCodec\JsonDecoder;

try {
    $data = JsonDecoder::toObject('{"name":"John"}');
} catch (JsonUnexpectedTypeException $e) {
    // JSON was valid, but the top-level value was not an object
} catch (JsonDecodeException $e) {
    // JSON decoding failed
}

Custom adapters

Custom adapters can be passed to JsonEncoder or JsonDecoder when you need to replace the default implementation.

Application code should normally use the public API:

use Snortlin\JsonCodec\JsonEncoder;

$encoder = new JsonEncoder();

$json = $encoder->encode([
    'name' => 'John',
]);

use Snortlin\JsonCodec\JsonDecoder;

$decoder = new JsonDecoder();

$data = $decoder->decode('{"name":"John"}');

The adapter interfaces are intended for implementing integrations, not for direct usage in application code.

Adapter selection

By default, the library chooses the best available adapter automatically.

The factory checks for compatible simdjson_* functions and selects the matching adapter when they are available. This makes it possible to use extensions such as awesomized/simdjson-plus-php-ext without changing application code.

For encoding:

1. SimdJsonEncoderAdapter if simdjson_encode() exists
2. NativeJsonEncoderAdapter otherwise

For decoding:

1. SimdJsonDecoderAdapter if simdjson_decode() exists
2. NativeJsonDecoderAdapter otherwise

License

MIT