JsonMapper PHP Library

JsonMapper is a PHP library designed to map nested JSON structures onto your own PHP model classes. It converts JSON data into nested objects and arrays by hydrating class properties based on your existing class definitions.

Key features include:

• No Schema Required: It does not rely on JSON schemas; it uses your PHP class definitions instead.
• Automatic Type Detection: It determines property types by parsing:
  • PHP type declarations
  • @var docblock annotations
  • Type hints in setter methods
• Zero Modification: You do not need to add JSON-specific code to your model classes; it works by parsing existing docblocks.
• No Dependencies: The library is standalone.

This process is similar to the native SOAP parameter mapping provided by PHP's SoapClient, but optimized for JSON.

Benefits

• IDE Support: Provides autocompletion in IDEs because you work with real PHP objects.
• Domain Logic: Allows you to easily add comfort methods and domain logic directly to your data model classes.
• Decoupling: Your JSON API can change without breaking applications, as long as your model classes remain consistent.

Drawbacks

• Manual Model Creation: Because JsonMapper does not rely on external schemas (like json-schema), model classes must be written by hand and cannot be automatically generated from a schema.

To use JsonMapper in your PHP project, install it via Composer from Packagist.

$ composer require netresearch/jsonmapper

To use JsonMapper, install it via Composer, instantiate the JsonMapper class, and use either map() for single objects or mapArray() for collections.

• Use map($jsonData, $target) to map JSON data to a single object instance or a class name.
• Use mapArray($jsonData, $container, $className) to map an array of JSON objects into a collection. The $container can be an array(), ArrayObject, or any class implementing ArrayAccess.

<?php
require 'autoload.php';
$mapper = new JsonMapper();

// Map to an object instance
$contactObject = $mapper->map($jsonContact, new Contact());
// Or map using a class name
$contactObject = $mapper->map($jsonContact, Contact::class);

// Map an array of objects
$contactsArray = $mapper->mapArray(
    $jsonContacts, array(), 'Contact'
);

If bExceptionOnUndefinedProperty is set to false, you can provide a callback to undefinedPropertyHandler to handle JSON properties that do not exist in the target PHP class. This allows you to dynamically map unknown data to specific properties or handle it manually.

Callback Signature: function(object $object, string $name, mixed $value): ?string

If the callback returns a string (the name of a property), JsonMapper will attempt to map the value to that returned property name instead.

By default, JsonMapper throws an exception if a JSON property is null unless the PHP property is explicitly marked as nullable (e.g., ?int or int|null).

• To allow null values for all properties without declaring them nullable: set $bStrictNullTypes = false;.
• To allow null values inside arrays without declaring them nullable (e.g., array[string|null]): set $bStrictNullTypesInArrays = false;.

You can instruct JsonMapper to call a specific method on every object after it has been successfully mapped. This is useful for initialization or validation logic.

Set postMappingMethod to the name of the method (as a string) that should be called on the mapped objects.

$jm = new JsonMapper();
$jm->postMappingMethod = 'afterMapping';
$jm->map(...);

// You can also pass arguments to the callback
$jm->postMappingMethodArguments = [23, 'foo'];
$jm->map(...);

If a property is typed as an abstract class or an interface, JsonMapper cannot instantiate it directly. Use the $classMap property to map the abstract type to a concrete implementation.

You can provide a string mapping or a callable for dynamic determination.

// String mapping
$jm = new JsonMapper();
$jm->classMap['Foo'] = 'Bar'; // Maps Foo to Bar
$jm->map(...);

// Dynamic mapping via callable
$mapper = function ($class, $jvalue) {
    // logic to determine class
    return 'DateTime';
};

$jm = new JsonMapper();
$jm->classMap['Foo'] = $mapper;
$jm->map(...);

Use the $classFactories property to define custom logic for how specific classes are instantiated. This is useful for complex types like DateTime where you want to control the constructor arguments based on the JSON value.

$jm = new JsonMapper();
$jm->classFactories[\DateTime::class] = function ($jvalue) {
    if (preg_match('/^\d{4}-\d{2}-\d{2}$/', $jvalue)) {
        return new \DateTime($jvalue);
    } else {
        throw new \Exception('Invalid date pattern');
    }
};
$jm->map(...);