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

.. image:: https://img.shields.io/packagist/v/apimatic/jsonmapper.svg?style=flat
   :target: https://packagist.org/packages/apimatic/jsonmapper
.. image:: https://img.shields.io/packagist/dm/apimatic/jsonmapper.svg?style=flat
   :target: https://packagist.org/packages/apimatic/jsonmapper
.. image:: https://github.com/apimatic/jsonmapper/workflows/Tests/badge.svg
   :target: https://github.com/apimatic/jsonmapper/actions?query=workflow%3ATests
.. image:: https://img.shields.io/packagist/l/apimatic/jsonmapper.svg?style=flat
   :target: https://packagist.org/packages/apimatic/jsonmapper

Takes data retrieved from a JSON__ 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

__ http://json.org/


.. contents::

============
Pro & contra
============

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
=========
- Model classes need to be written by hand

  Since JsonMapper does not rely on any schema information
  (e.g. from `json-schema`__), model classes cannot be generated
  automatically.

__ http://json-schema.org/


=====
Usage
=====

Basic usage
===========
#. Register an autoloader that can load `PSR-0`__ compatible classes.
#. Create a ``JsonMapper`` object instance
#. Call the ``map`` or ``mapArray`` method, depending on your data

Map a normal object:

.. code:: php

    <?php
    require 'autoload.php';
    $mapper = new JsonMapper();
    $contactObject = $mapper->map($jsonContact, new Contact());
    ?>

Map an array of objects:

.. code:: php

    <?php
    require 'autoload.php';
    $mapper = new JsonMapper();
    $contactsArray = $mapper->mapArray(
        $jsonContacts, new ArrayObject(), 'Contact'
    );
    ?>

__ http://www.php-fig.org/psr/psr-0/


Example
=======
JSON from a address book web service:

.. code:: javascript

    {
        'name':'Sheldon Cooper',
        'address': {
            'street': '2311 N. Los Robles Avenue',
            'city': 'Pasadena'
        }
    }

Your local ``Contact`` class:

.. code:: php

    <?php
    class Contact
    {
        /**
         * Full name
         * @var string
         */
        public $name;

        /**
         * @var Address
         */
        public $address;
    }
    ?>

Your local ``Address`` class:

.. code:: php

    <?php
    class Address
    {
        public $street;
        public $city;

        public function getGeoCoords()
        {
            //do something with the $street and $city
        }
    }
    ?>

Your application code:

.. code:: php

    <?php
    $json = json_decode(file_get_contents('http://example.org/bigbang.json'));
    $mapper = new JsonMapper();
    $contact = $mapper->map($json, new Contact());

    echo "Geo coordinates for " . $contact->name . ": "
        . var_export($contact->address->getGeoCoords(), true);
    ?>

Letting JsonMapper create the instances for you
===============================================

Map a normal object (works similarly to ``map``):

.. code:: php

    $mapper = new JsonMapper();
    $contactObject = $mapper->mapClass($jsonContact, 'Contact');

Map an array of objects (works similarly to ``mapArray``):

.. code:: php

    $mapper = new JsonMapper();
    $contactsArray = $mapper->mapClassArray($jsonContacts, 'Contact');

Map a value with any combination of types e.g oneOf(string,int) or anyOf(string,Contact):

.. code:: php

    $mapper = new JsonMapper();
    $contactObject = $mapper->mapFor($value, 'oneOf(string,Contact)');

Property type documentation
===========================
``JsonMapper`` uses several sources to detect the correct type of
a property:

#. The setter method (``set`` + ``ucwords($propertyname)``) is inspected.

   Underscores make the next letter uppercase, which means that
   for a JSON property ``foo_bar_baz`` a setter method of
   ``setFooBarBaz`` is used.

   #. If it has a type hint in the method signature, this type used::

        public function setPerson(Contact $person) {...}

   #. The method's docblock is inspected for ``@param $type`` annotations::

        /**
         * @param Contact $person Main contact for this application
         */
        public function setPerson($person) {...}

   #. If no type could be detected, the plain JSON value is passed
      to the setter method.

#. ``@var $type`` docblock annotation of class properties::

    /**
     * @var \my\application\model\Contact
     */
    public $person;

   Note that the property has to be public to be used directly.

   If no type could be detected, the property gets the plain JSON value.

   If a property can not be found, JsonMapper tries to find the property
   in a case-insensitive manner.
   A JSON property ``isempty`` would then be mapped to a PHP property
   ``isEmpty``.

To map a JSON key to an arbitrarily named class property, you can use 
the ``@maps`` annotation:

.. code:: php

    /**
     * @var \my\application\model\Person
     * @maps person_object
     */
    public $person;

Supported type names:

- Simple types:

  - ``string``
  - ``bool``, ``boolean``
  - ``int``, ``integer``
  - ``float``
  - ``array``
  - ``object``
- Class names, with and without namespaces
- Arrays of simple types and class names:

  - ``int[]``
  - ``Contact[]``
- ArrayObjects of simple types and class names:

  - ``ContactList[Contact]``
  - ``NumberList[int]``
- Nullable types:

  - ``int|null`` - will be ``null`` if the value in JSON is
    ``null``, otherwise it will be an integer

ArrayObjects and extending classes are treated as arrays.

Variables without a type or with type ``mixed`` will get the
JSON value set directly without any conversion.

See `phpdoc's type documentation`__ for more information.

__ http://phpdoc.org/docs/latest/references/phpdoc/types.html


Simple type mapping
-------------------
When an object shall be created but the JSON contains a simple type
only (e.g. string, float, boolean), this value is passed to
the classes' constructor. Example:

PHP code:

.. code:: php

    /**
     * @var DateTime
     */
    public $date;

JSON:

.. code:: js

    {"date":"2014-05-15"}

This will result in ``new DateTime('2014-05-15')`` being called.

Custom property initialization
------------------------------

You can use the ``@factory`` annotation to specify a custom method that
will be called to get the value to be assigned to the property.

.. code:: php

    /**
     * @factory MyUtilityClass::createDate
     */
    public $date;

Here, ``createDate`` method in the ``MyUtilityClass`` is called with the
raw value for ``date`` property and the value returned by the factory method
is then assigned to the ``date`` property.

The factory method should return true when tested with ``is_callable``, otherwise
an exception will be thrown.

The factory annotation can be used with other annotations such as ``@var``; however,
only the value created by the factory method will be used while other typehints and
initialization methods for the property will be ignored.

Logging
=======
JsonMapper's ``setLogger()`` method supports all PSR-3__ compatible
logger instances.

Events that get logged:

- JSON data contain a key, but the class does not have a property
  or setter method for it.
- Neither setter nor property can be set from outside because they
  are protected or private

__ http://www.php-fig.org/psr/psr-3/


Handling invalid or missing data
================================
During development, APIs often change.
To get notified about such changes, JsonMapper may throw exceptions
in case of either missing or yet unknown data.


Unknown properties
------------------
When JsonMapper sees properties in the JSON data that are
not defined in the PHP class, you can let it throw an exception
by setting ``$bExceptionOnUndefinedProperty``:

.. code:: php

    $jm = new JsonMapper();
    $jm->bExceptionOnUndefinedProperty = true;
    $jm->map(...);

To process unknown properties yourself, you can set a method on the
class as a collection method:

.. code:: php

    $jm = new JsonMapper();
    $mapper->sAdditionalPropertiesCollectionMethod = 'addAdditionalProperty';
    $jm->map(...);

Here, the ``addAdditionalProperty()`` method will be called with a ``name`` and
a ``value`` argument.

Missing properties
------------------
Properties in your PHP classes can be marked as "required" by
putting ``@required`` in their docblock:

.. code:: php

    /**
     * @var string
     * @required
     */
    public $someDatum;

When the JSON data do not contain this property, JsonMapper will throw
an exception when ``$bExceptionOnMissingData`` is activated:

.. code:: php

    $jm = new JsonMapper();
    $jm->bExceptionOnMissingData = true;
    $jm->map(...);


Passing arrays to ``map()``
---------------------------
You may wish to pass array data into ``map()`` that you got by calling

.. code:: php

    json_decode($jsonString, true)

By default, JsonMapper will throw an exception because ``map()`` requires
an object as first parameter.
You can circumvent that by setting ``$bEnforceMapType`` to ``false``:

.. code:: php

    $jm = new JsonMapper();
    $jm->bEnforceMapType = false;
    $jm->map(...);


Handling polymorphic responses
==============================

JsonMapper allows you to map a JSON object to a derived class based on a discriminator
field. The discriminator field's value is used to decide which class this JSON object
should be mapped to.

Your local ``Person`` class:

.. code:: php

    <?php
    /**
     * @discriminator type
     * @discriminatorType person
     */
    class Person
    {
        public $name;
        public $age;
        public $type;
    }

Your local ``Employee`` class:

.. code:: php

    <?php
    /**
     * @discriminator type
     * @discriminatorType employee
     */
    class Employee extends Person
    {
        public $employeeId;
    }

Your application code:

.. code:: php

    $mapper = new JsonMapper();
    $mapper->arChildClasses['Person'] = ['Employee'];
    $mapper->arChildClasses['Employee'] = [];
    $person = $mapper->mapClass($json, 'Person');

Now, if the value of the ``type`` key in JSON is ``"person"`` then an instance of
a ``Person`` class is returned. However, if the ``type`` is ``"employee"`` then
an instance of ``Employee`` class is returned.

Classes need to be registered in ``arChildClasses`` before being used with 
discriminator.

Note that there can only be one discriminator field in an object hierarchy.

Polymorphic responses also work if the polymorphic class is embedded as a field or 
in an array.

To map an array of classes, use the ``mapArrayClass`` which will create the right
type of objects by examining the ``discriminatorType`` value.

============
Installation
============

Supported PHP Versions
======================
- PHP 5.6
- PHP 7.0
- PHP 7.1
- PHP 7.2
- PHP 7.4
- PHP 8.0
- PHP 8.1
- PHP 8.2


Install the Package
============
From Packagist__::

    $ composer require apimatic/jsonmapper

__ https://packagist.org/packages/apimatic/jsonmapper


================
Related software
================
- `Jackson's data binding`__ for Java
- `Johannes Schmitt Serializer`__ for PHP

__ http://wiki.fasterxml.com/JacksonDataBinding
__ http://jmsyst.com/libs/serializer


================
About JsonMapper
================

License
=======
JsonMapper is licensed under the `OSL 3.0`__.

__ http://opensource.org/licenses/osl-3.0


Coding style
============
JsonMapper follows the `PEAR Coding Standards`__.

__ http://pear.php.net/manual/en/standards.php


Author
======
`Christian Weiske`__, `Netresearch GmbH & Co KG`__

__ mailto:christian.weiske@netresearch.de
__ http://www.netresearch.de/