README

JsonMapper is a PHP library that allows you to map a JSON response to your PHP objects that are either annotated using doc blocks or use typed properties. For more information see the project website: https://jsonmapper.net/

Why use JsonMapper

Continuously mapping your JSON responses to your own objects becomes tedious and is error-prone. Not mentioning the tests that need to be written for said mapping.

JsonMapper has been built with the most common usages in mind. To allow for those edge cases which are not supported by default, it can easily be extended as its core has been designed using middleware.

JsonMapper supports the following features

DocBlock annotations and typed properties
Namespace resolving, so your models can stay organised the way you want them
Custom constructors, including readonly properties and classes on PHP 8.1+
Enums on PHP 8.1+
Mapping from names that do not match your model, through PHP attributes, an explicit rename mapping, or case conversion
Value transformation through a callback
Interfaces and abstract classes, through factories you register
Strict scalar casting, which throws rather than coercing a mismatched type
A final callback once an object is filled, and debug logging of the mapping as it happens
First-party Laravel and Symfony integrations, plus mapping straight onto Eloquent models

Installing JsonMapper

The installation of JsonMapper can easily be done with Composer

$ composer require json-mapper/json-mapper

The example shown above assumes that composer is on your $PATH.

How to use JsonMapper

Given the following class definition

class User
{
    /** @var string */
    private $name;

    public function getName(): string
    {
        return $this->name;
    }

    public function setName(string $name): void
    {
        $this->name = $name;
    }
}

Combined with the following JsonMapper code as part of your application

$mapper = (new \JsonMapper\JsonMapperFactory())->default();

$user = $mapper->mapToClassFromString('{ "name": "John Doe" }', User::class);

echo $user->getName(); // "John Doe"

The property is private, so JsonMapper fills it through setName(). A non-public property with no matching setter raises a RuntimeException, so your model keeps its encapsulation either way.

Customizing JsonMapper

Writing your own middleware has been made as easy as possible with an AbstractMiddleware that can be extended with the functionality you need for your project.

$mapper = (new \JsonMapper\JsonMapperFactory())->bestFit();
$mapper->push(new class extends \JsonMapper\Middleware\AbstractMiddleware {
    public function handle(
        \stdClass $json,
        \JsonMapper\Wrapper\ObjectWrapper $object,
        \JsonMapper\ValueObjects\PropertyMap $map,
        \JsonMapper\JsonMapperInterface $mapper
    ): void {
        /* Custom logic here */
    }
});

Contributing

Please refer to CONTRIBUTING.md for information on how to contribute to JsonMapper.

List of Contributors

Thanks to everyone who has contributed to JsonMapper! You can find a detailed list of people that contributed to JsonMapper on GitHub.

Sponsoring

This project is sponsored by JetBrains providing a license for PhpStorm to continue building on JsonMapper.

License

The MIT License (MIT). Please see License File for more information.

json-mapper / json-mapper

Package info

Security

Fund package maintenance!

Statistics