WebFiori Json

A PHP library for creating and parsing JSON and JSONx strings. Supports all PHP scalar types, arrays, and objects with flexible property naming styles.

Table of Contents

• Key Features
• Supported PHP Versions
• Installation
• Quick Start
• Usage
  • Working With Arrays
  • Working With Objects
  • Property Naming Styles
  • Decoding JSON
  • Typed Deserialization
  • Saving to File
  • Converting to Array
  • JSONx
• Error Handling
• API Reference
• Testing
• Contributing
• License
• Support
• Changelog

Key Features

• Create well-formatted JSON strings from any PHP value (scalars, arrays, objects)
• Decode JSON strings and files into Json objects
• Typed deserialization via Json::decodeAs() with nested object hydration
• Flexible property naming styles: camelCase, kebab-case, snake_case, or none
• Letter case control: same, upper, lower
• Custom object serialization via the JsonI interface
• Auto-mapping of plain objects via public getter methods and public properties
• Auto-detection of associative arrays as JSON objects
• Attribute-based control: #[JsonProperty], #[JsonIgnore], #[JsonType]
• Application-wide defaults via Json::setDefaults()
• JSONx output (XML representation of JSON)
• Save JSON output directly to a file

Supported PHP Versions

Build Status

Installation

composer require webfiori/jsonx

Quick Start

useWebFiori\Json\Json;
$json = newJson([
'name' => 'Ibrahim',
'age' => 30,
'married' => false,
'score' => 9.5,
'notes' => null,
]);
echo$json;

Output:

{"name":"Ibrahim","age":30,"married":false,"score":9.5,"notes":null}

You can also build the object incrementally:

$json = newJson();
$json->addString('name', 'Ibrahim');
$json->addNumber('age', 30);
$json->addBoolean('married', false);
$json->addNull('notes');

Usage

Working With Arrays

$json = newJson();
// Indexed array$json->addArray('tags', ['php', 'json', 'api']);
// Associative arrays are automatically encoded as JSON objects$json->addArray('address', ['city' => 'Riyadh', 'country' => 'SA']);
echo$json;

Output:

{"tags":["php","json","api"],"address":{"city":"Riyadh","country":"SA"}}

Working With Objects

Using JsonI Interface

Implement JsonI to fully control how an object is serialized:

useWebFiori\Json\Json;
useWebFiori\Json\JsonI;
class User implements JsonI {
publicfunction__construct(
privatestring$username,
privatestring$email
) {}
publicfunctiontoJSON(): Json {
returnnewJson(['username' => $this->username, 'email' => $this->email]);
}
}
$json = newJson();
$json->addObject('user', newUser('ibrahim', 'ibrahim@example.com'));
echo$json;

Output:

{"user":{"username":"ibrahim","email":"ibrahim@example.com"}}

Auto-Mapping Objects

Objects that don't implement JsonI are mapped automatically using:

1. Public getter methods — any zero-parameter method prefixed with get is called. The property name is derived by stripping get (e.g. getName() → Name with style none, or name with style camel).
2. Public properties — extracted via reflection and added as-is.

Use #[JsonIgnore] to exclude specific getters or properties, and #[JsonProperty] to override the output name:

useWebFiori\Json\Json;
useWebFiori\Json\JsonIgnore;
useWebFiori\Json\JsonProperty;
class Product {
#[JsonProperty('product_sku')]
publicstring$sku = 'ABC-001';
#[JsonIgnore]
publicstring$internalCode = 'X-99';
privatestring$name;
privatefloat$price;
publicfunction__construct(string$name, float$price) {
$this->name = $name;
$this->price = $price;
}
publicfunctiongetName(): string { return$this->name; }
publicfunctiongetPrice(): float { return$this->price; }
#[JsonProperty('on_sale')]
publicfunctiongetAvailable(): bool { returntrue; }
#[JsonIgnore]
publicfunctiongetSecretMargin(): float { return0.42; }
}
$json = newJson([], 'snake');
$json->addObject('product', newProduct('Keyboard', 49.99));
echo$json;

Output:

{"product":{"name":"Keyboard","price":49.99,"on_sale":true,"product_sku":"ABC-001"}}

Property Naming Styles

Four naming styles are supported: none (default), camel, snake, kebab.
Three letter cases are supported: same (default), upper, lower.

$data = ['first-name' => 'Ibrahim', 'last-name' => 'Al-Shikh'];
echonewJson($data, 'none') . "\n"; // {"first-name":"Ibrahim","last-name":"Al-Shikh"}echonewJson($data, 'camel') . "\n"; // {"firstName":"Ibrahim","lastName":"Al-Shikh"}echonewJson($data, 'snake') . "\n"; // {"first_name":"Ibrahim","last_name":"Al-Shikh"}echonewJson($data, 'kebab') . "\n"; // {"first-name":"Ibrahim","last-name":"Al-Shikh"}

Set application-wide defaults:

Json::setDefaults(style: 'camel', case: 'lower', formatted: false);

Decoding JSON

Decode a JSON string:

$json = Json::decode('{"name":"Ibrahim","age":30}');
echo$json->get('name'); // Ibrahim

Read from a file:

$json = Json::fromJsonFile('/path/to/file.json');

Typed Deserialization

Deserialize JSON directly into typed objects:

class User {
publicfunction__construct(
privatestring$username,
privatestring$email
) {}
publicfunctiongetUsername(): string { return$this->username; }
publicfunctiongetEmail(): string { return$this->email; }
}
$user = Json::decodeAs('{"username":"ibrahim","email":"a@b.com"}', User::class);
echo$user->getUsername(); // ibrahim

Nested objects are resolved automatically via constructor type hints. Use #[JsonType] for arrays of objects:

useWebFiori\Json\JsonType;
class Order {
publicfunction__construct(
privateUser$customer,
#[JsonType(LineItem::class, isArray: true)]
privatearray$items
) {}
}
$order = Json::decodeAs($jsonString, Order::class);
$order->getCustomer(); // User instance$order->getItems(); // LineItem[] array

Runtime type mapping without attributes:

$json = Json::decode($jsonString);
$json->setTypeMap([
'customer' => User::class,
'items' => [LineItem::class],
]);
$json->get('customer'); // User instance$json->get('items'); // LineItem[] array

Saving to File

$json = newJson(['name' => 'Ibrahim', 'age' => 30]);
$json->toJsonFile('data', '/path/to/directory', true);
// Creates /path/to/directory/data.json

Converting to Array

The toArray() method converts a Json object to a plain PHP associative array without the overhead of encoding to a JSON string and decoding it back:

$json = newJson([
'name' => 'Ibrahim',
'age' => 30,
'active' => true,
]);
$address = newJson(['city' => 'Riyadh', 'country' => 'SA']);
$json->add('address', $address);
$array = $json->toArray();
// Result:// [// 'name' => 'Ibrahim',// 'age' => 30,// 'active' => true,// 'address' => [// 'city' => 'Riyadh',// 'country' => 'SA',// ],// ]

This is useful when passing structured data to functions expecting arrays, PHPUnit assertions, or merging with other arrays. See examples/11-to-array.php for more examples.

JSONx

JSONx is an IBM standard that represents JSON as XML:

$json = newJson(['name' => 'Ibrahim', 'age' => 30, 'isEmployed' => true]);
echo$json->toJSONxString();

Output:

<?xml version="1.0" encoding="UTF-8"?>
<json:objectxsi:schemaLocation="http://www.datapower.com/schemas/json jsonx.xsd"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:json="http://www.ibm.com/xmlns/prod/2009/jsonx">
<json:stringname="name">Ibrahim</json:string>
<json:numbername="age">30</json:number>
<json:booleanname="isEmployed">true</json:boolean>
</json:object>

Error Handling

All errors throw \WebFiori\Json\JsonException:

try {
$json = Json::decode('{invalid json}');
} catch (\WebFiori\Json\JsonException$e) {
echo$e->getMessage();
}

API Reference

Classes

Class	Description
Json	Main class for building, reading, and deserializing JSON data
JsonI	Interface for custom object serialization
JsonConverter	Handles serialization to JSON and JSONx strings
JsonDeserializer	Handles typed deserialization of JSON into objects
Property	Represents a single JSON property
CaseConverter	Converts property names between naming styles
JsonTypes	Constants for JSON data types
JsonException	Exception thrown on JSON errors

Attributes

Attribute	Target	Description
#[JsonIgnore]	Method, Property	Exclude from serialization
#[JsonProperty(name)]	Method, Property	Override output name
#[JsonType(class, isArray)]	Parameter, Property	Specify type for deserialization

Key Methods — Json

Method	Description
add(string $key, mixed $value, bool $arrayAsObj = false): bool	Add any value
addString(string $key, string $val): bool	Add a string
addNumber(string $key, int|float $value): bool	Add a number
addBoolean(string $key, bool $val = true): bool	Add a boolean
addNull(string $key): bool	Add a null value
addArray(string $key, array $value, bool $asObject = false): bool	Add an array
addObject(string $key, object &$val): bool	Add an object
get(string $key): mixed	Get a property value
hasKey(string $key): bool	Check if a key exists
remove(string $key): ?Property	Remove a property
setPropsStyle(string $style, string $lettersCase = 'same'): void	Change naming style
setIsFormatted(bool $bool): void	Toggle formatted output
setTypeMap(array $map): void	Set type map for typed deserialization via get()
toJSONString(): string	Get JSON string
toJSONxString(): string	Get JSONx string
toArray(): array	Get plain PHP associative array
toJsonFile(string $fileName, string $path, bool $override = false): void	Save to file
Json::decode(string $jsonStr): Json	Decode a JSON string
Json::decodeAs(string $jsonStr, string $className): object	Decode and hydrate a typed object
Json::fromJsonFile(string $path): Json	Load from a JSON file
Json::setDefaults(?string $style, ?string $case, ?bool $formatted): void	Set application-wide defaults
Json::resetDefaults(): void	Reset to library defaults

Testing

# Install dependencies
composer install
# Run tests
composer test

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

This library is licensed under the MIT License. See the LICENSE file for more details.

Support

If you encounter any issues, please open an issue on GitHub.

Changelog

See CHANGELOG.md for a list of changes.