Structured, type-safe, immutable JSON objects.





Fund package maintenance!

v1.2.1 2023-07-13 13:20 UTC


Built on top of PHP.Gt/DataObject, this repository adds JSON-specific compatibility. The main usage will be via the JsonObjectBuilder class that can be used to build a type of JsonObject from a JSON string or decoded JSON object (from json_decode).

The purpose of using these classes to represent decoded JSON data is to provide a type-safe, immutable interface to the enclosed data.

Build status Code quality Code coverage Current version PHP.Gt/Json documentation

The abstract JsonObject class extends the DataObject base class to represent the root element of a JSON object. In JSON, this may not necessarily be a key-value-pair object.

The following JSON strings can all be successfully decoded:

  • {"type": "key-value-pair"} - a typical key-value-pair object
  • [{"name": "first"}, {"name": "second"} - an array of objects
  • 0 - an integer
  • 1.05 - a floating point
  • false - a boolean
  • "Today is going to be a good day" - a string
  • null - a null

Because of this, the base DataObject would be unable to represent the different types of scalar value in a type-safe way. The JsonObjectBuilder class returns a new instance of the abstract JsonObject class which is one of the following types:

  • JsonKvpObject - identical features to DataObject with type-safe getters for its keys
  • JsonPrimitive - a representation of the primitive value, further broken down into types JsonArrayPrimitive, JsonBoolPrimitive, JsonFloatPrimitive, JsonIntPrimitive, JsonNullPrimitive and JsonStringPrimitive.

Usage example

use Gt\Json\JsonObjectBuilder;
use Gt\Json\JsonKvpObject;
use Gt\Json\JsonPrimitive\JsonPrimitive;

$response = file_get_contents("");
$builder = new JsonObjectBuilder();
$jsonObject = $builder->fromJsonString($response);

if($jsonObject instanceof JsonKvpObject) {
	$id = $jsonObject->getInt("id");
elseif($jsonObject instanceof JsonPrimitive) {
	$id = $jsonObject->getPrimitiveValue();

echo "Requested ID is: $id";

Fetch API

Check out the PHP implementation of the Fetch API that uses this library to work with JSON endpoints asynchronously.