PHPackages                             apimatic/jsonmapper - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. apimatic/jsonmapper

ActiveLibrary[Utility & Helpers](/categories/utility)

apimatic/jsonmapper
===================

Map nested JSON structures onto PHP classes

3.1.7(6mo ago)248.0M—2.8%7[7 issues](https://github.com/apimatic/jsonmapper/issues)20OSL-3.0PHPPHP ^5.6 || ^7.0 || ^8.0CI passing

Since Jan 28Pushed 1mo ago4 watchersCompare

[ Source](https://github.com/apimatic/jsonmapper)[ Packagist](https://packagist.org/packages/apimatic/jsonmapper)[ RSS](/packages/apimatic-jsonmapper/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (2)Versions (49)Used By (20)

JsonMapper - map nested JSON structures onto PHP classes
========================================================

[](#jsonmapper---map-nested-json-structures-onto-php-classes)

[![https://img.shields.io/packagist/v/apimatic/jsonmapper.svg?style=flat](https://camo.githubusercontent.com/ab1b0e6208805d3f85aaa1d9506b8a0176506c8ab88e4c85dd828676cd8ae19a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6170696d617469632f6a736f6e6d61707065722e7376673f7374796c653d666c6174)](https://packagist.org/packages/apimatic/jsonmapper)[![https://img.shields.io/packagist/dm/apimatic/jsonmapper.svg?style=flat](https://camo.githubusercontent.com/8761ead09a9dc53ad0eaeacc204ecd780baf52e5b318f6a37333604d639ca082/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f6170696d617469632f6a736f6e6d61707065722e7376673f7374796c653d666c6174)](https://packagist.org/packages/apimatic/jsonmapper)[![](https://github.com/apimatic/jsonmapper/workflows/Tests/badge.svg)](https://github.com/apimatic/jsonmapper/actions?query=workflow%3ATests)[![https://sonarcloud.io/api/project_badges/measure?project=apimatic_jsonmapper&metric=coverage](https://camo.githubusercontent.com/a0b2d64aadec4b2cda06fe52a96d91a0c9082a5f5ca937344fce6cf1537b49b7/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d6170696d617469635f6a736f6e6d6170706572266d65747269633d636f766572616765)](https://sonarcloud.io/summary/new_code?id=apimatic_jsonmapper)[![https://sonarcloud.io/api/project_badges/measure?project=apimatic_jsonmapper&metric=sqale_rating](https://camo.githubusercontent.com/ff9546f117662b68c6ada3c8dcd6fd9e5c9af6e26f0dd743d67dc8517ca1f526/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d6170696d617469635f6a736f6e6d6170706572266d65747269633d7371616c655f726174696e67)](https://sonarcloud.io/summary/new_code?id=apimatic_jsonmapper)[![https://sonarcloud.io/api/project_badges/measure?project=apimatic_jsonmapper&metric=vulnerabilities](https://camo.githubusercontent.com/f2eab14bffce0086f9fe71b95e7bfc0061d4f7c841bed50372263903b0e96887/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d6170696d617469635f6a736f6e6d6170706572266d65747269633d76756c6e65726162696c6974696573)](https://sonarcloud.io/summary/new_code?id=apimatic_jsonmapper)[![https://img.shields.io/packagist/l/apimatic/jsonmapper.svg?style=flat](https://camo.githubusercontent.com/10e757381dc7fb9918935dc3d52c5f687643680425578b6b6c158d59fd27cfae/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6170696d617469632f6a736f6e6d61707065722e7376673f7374796c653d666c6174)](LICENSE)Takes data retrieved from a [JSON](http://json.org/) web service and converts them into nested object and arrays - using your own model classes.

Starting from a base object, it maps JSON data on class properties, converting them into the correct simple types or objects.

It's a bit like the native SOAP parameter mapping PHP's `SoapClient`gives you, but for JSON. Note that it does not rely on any schema, only your class definitions.

Type detection works by parsing `@var` docblock annotations of class properties, as well as type hints in setter methods. If docblock comments, or comments in general are discarded through some configuration setting like `opcache.save_comments=0`, or any other similar configuration, an exception is thrown, blocking any further operation.

You do not have to modify your model classes by adding JSON specific code; it works automatically by parsing already-existing docblocks.

Keywords: deserialization, hydration

Contents

- [Pro & contra](#pro-contra)
    - [Benefits](#benefits)
    - [Drawbacks](#drawbacks)
- [Usage](#usage)
    - [Basic usage](#basic-usage)
    - [Example](#example)
    - [Letting JsonMapper create the instances for you](#letting-jsonmapper-create-the-instances-for-you)
    - [Property type documentation](#property-type-documentation)
        - [Simple type mapping](#simple-type-mapping)
        - [Custom property initialization](#custom-property-initialization)
    - [Logging](#logging)
    - [Handling invalid or missing data](#handling-invalid-or-missing-data)
        - [Unknown properties](#unknown-properties)
        - [Missing properties](#missing-properties)
        - [Passing arrays to `map()`](#passing-arrays-to-map)
    - [Handling polymorphic responses](#handling-polymorphic-responses)
- [Installation](#installation)
    - [Supported PHP Versions](#supported-php-versions)
    - [Install the Package](#install-the-package)
- [Related software](#related-software)
- [About JsonMapper](#about-jsonmapper)
    - [License](#license)
    - [Coding style](#coding-style)
    - [Author](#author)

[Pro & contra](#id13)
-------------------------

[](#pro--contra)

### [Benefits](#id14)

[](#benefits)

- Autocompletion in IDEs
- It's easy to add comfort methods to data model classes
- Your JSON API may change, but your models can stay the same - not breaking applications that use the model classes.

### [Drawbacks](#id15)

[](#drawbacks)

- Model classes need to be written by hand

    Since JsonMapper does not rely on any schema information (e.g. from [json-schema](http://json-schema.org/)), model classes cannot be generated automatically.

[Usage](#id16)
--------------

[](#usage)

### [Basic usage](#id17)

[](#basic-usage)

1. Register an autoloader that can load [PSR-0](http://www.php-fig.org/psr/psr-0/) compatible classes.
2. Create a `JsonMapper` object instance
3. Call the `map` or `mapArray` method, depending on your data

Map a normal object:

```

```

Map an array of objects:

```