README

Introduction

A PHP 8.5+ library for converting JSON data to typed entities and back, with support for lazy-loading collections, mutable data structures, and structured entity design. Useful for structured JSON APIs, configuration parsing, and object-based manipulation of hierarchical JSON data.

Features

• Object-oriented JSON mapping
• Conversion from JSON to typed entities and back
• Lazy-loading collections for efficient memory usage
• Entity objects are mutable and can be freely modified after creation
• Strict type support with automatic casting and codec transformations
• Native support for nested structures and arrays
• Easy integration with configuration or API responses

Installation

composer require matraux/json-orm

PHP compatibility

This package provides separate major versions for different PHP baselines.

Examples

See Definitions for how to define your own entities and collections.

See Read for full reading examples.

use Matraux\JsonOrm\Json\SimpleExplorer;

// Load data from JSON string or file
$explorer = SimpleExplorer::fromString('[{"CUSTOM_ID":1,"name":"First"}]');

// Create typed collection from JSON
$collection = CommonCollection::fromExplorer($explorer);

$entity = $collection[0];
echo $entity->name; // "First"

See Write for writing examples.

// Create collection and insert entity
$collection = CommonCollection::create();

$entity = $collection->createEntity();
$entity->name = 'Example';

echo json_encode($collection);
// '[{"name":"Example"}]'

Development

See Development for debug, test instructions, static analysis, and coding standards.

Support

For bug reports and feature requests, please use the issue tracker.