README

Safe JSON parsing with exceptions, schema validation, and typed getters.

Requirements

• PHP 8.2+

Installation

composer require philiprehberger/php-safe-json

Usage

Decoding JSON

use PhilipRehberger\SafeJson\SafeJson;

$obj = SafeJson::decode('{"name":"Alice","age":30,"active":true}');

$obj->string('name');   // "Alice"
$obj->int('age');       // 30
$obj->bool('active');   // true

Dot Notation for Nested Access

$obj = SafeJson::decode('{"user":{"address":{"city":"Vienna"}}}');

$obj->string('user.address.city'); // "Vienna"
$obj->has('user.address.city');    // true
$obj->has('user.address.zip');     // false

Nested Objects

$obj = SafeJson::decode('{"user":{"name":"Alice"}}');

$user = $obj->object('user');
$user->string('name'); // "Alice"

Safe Decoding (No Exceptions)

$obj = SafeJson::tryDecode('{invalid}');
// Returns null instead of throwing

$obj = SafeJson::tryDecode('{"valid":true}');
// Returns JsonObject

Default Values

$obj = SafeJson::decode('{"name":"Alice"}');

$obj->get('name');              // "Alice"
$obj->get('missing', 'default'); // "default"
$obj->get('missing');           // throws JsonKeyException

Nullable Accessors

$obj = SafeJson::decode('{"name":"Alice","age":30}');

$obj->stringOrNull('name');    // "Alice"
$obj->stringOrNull('missing'); // null
$obj->intOrNull('name');       // null (wrong type)
$obj->intOrNull('age');        // 30

Merging Objects

$a = SafeJson::decode('{"name":"Alice","age":30}');
$b = SafeJson::decode('{"name":"Bob","email":"bob@example.com"}');

$merged = $a->merge($b);
$merged->string('name');  // "Bob" (overridden)
$merged->int('age');      // 30 (kept from $a)
$merged->string('email'); // "bob@example.com" (added from $b)

JSON Path Querying

$obj = SafeJson::decode('{"users":[{"name":"Alice","age":30},{"name":"Bob","age":25}]}');

$obj->query('$.users[*].name');       // ['Alice', 'Bob']
$obj->query('$.users[0].age');        // [30]
$obj->query('$..name');               // ['Alice', 'Bob'] (recursive descent)
$obj->query('$.users[0:1]');          // [['name' => 'Alice', 'age' => 30]]

Supported syntax: $ (root), .key (child), [0] (index), [*] (wildcard), ..key (recursive descent), [0:3] (slice), ['key'] (bracket notation).

JSON Diffing

$changes = SafeJson::diff(
    '{"name":"Alice","age":30}',
    '{"name":"Bob","age":30,"email":"bob@example.com"}'
);

// [
//   ['op' => 'replace', 'path' => 'name', 'value' => 'Bob', 'old' => 'Alice'],
//   ['op' => 'add', 'path' => 'email', 'value' => 'bob@example.com'],
// ]

Streaming Decode

// Memory-efficient decoding of large JSON arrays
foreach (SafeJson::decodeStream('/path/to/large-file.json') as $element) {
    // Each element is decoded one at a time
    // Only one element is held in memory
}

Encoding

$json = SafeJson::encode(['key' => 'value']);
// '{"key":"value"}'

$json = SafeJson::tryEncode($data);
// Returns null on failure instead of throwing

Serialization

$obj = SafeJson::decode('{"key":"value"}');

$obj->toArray(); // ['key' => 'value']
$obj->toJson();  // '{"key":"value"}'
json_encode($obj); // '{"key":"value"}' (JsonSerializable)
(string) $obj;     // '{"key":"value"}' (Stringable)

API

SafeJson

JsonObject

All key-based methods support dot notation for nested access (e.g., user.address.city).

JsonPath

JsonDiff

StreamDecoder

Exceptions

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT