philiprehberger/php-safe-json

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

v1.0.2 2026-03-17 20:06 UTC

Requires

• php: ^8.2

Requires (Dev)

• laravel/pint: ^1.0
• phpstan/phpstan: ^1.12|^2.0
• phpunit/phpunit: ^11.0

MIT

• Philip Rehberger

• json
• parse
• encode
• decode
• typed
• safe

README

Safe JSON parsing with exceptions and typed getters for PHP.

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

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

Method	Description
decode(string $json): JsonObject	Decode JSON string, throws JsonDecodeException on failure
tryDecode(string $json): ?JsonObject	Decode JSON string, returns null on failure
encode(mixed $data, int $flags = 0): string	Encode to JSON string, throws on failure
tryEncode(mixed $data, int $flags = 0): ?string	Encode to JSON string, returns null on failure

JsonObject

Method	Description
string(string $key): string	Get string value by key
int(string $key): int	Get integer value by key
float(string $key): float	Get float value by key (accepts integers)
bool(string $key): bool	Get boolean value by key
array(string $key): array	Get array value by key
object(string $key): JsonObject	Get nested JsonObject by key
get(string $key, mixed $default = null): mixed	Get value without type enforcement
has(string $key): bool	Check if key exists
toArray(): array	Return underlying array
toJson(int $flags = 0): string	Return JSON string

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

Exceptions

Exception	Thrown When
JsonDecodeException	Invalid JSON input
JsonEncodeException	Failed to encode data
JsonKeyException	Missing key or type mismatch

Development

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

License

MIT