Repository files navigation

Maps JSON data to strongly typed PHP DTOs.

This library provides an easy-to-use, secure, and powerful way to map JSON data to strongly typed PHP objects.

It reads parameter types & annotations defined on your class constructors to map JSON data to your DTOs, and can work with zero configuration.

This library is installable viaComposer:

composer require brick/json-mapper

This library requires PHP 8.1 or later.

While this library is still under development, it is well tested and considered stable enough to use in production environments.

The current releases are numbered0.x.y. When a non-breaking change is introduced (adding new methods, optimizing existing code, etc.),y is incremented.

When a breaking change is introduced, a new0.x version cycle is always started.

It is therefore safe to lock your project to a given release cycle, such as0.1.*.

If you need to upgrade to a newer release cycle, check therelease history for a list of changes introduced by each further0.x.0 version.

JsonMapper provides a single method,map(), which takes a JSON string and a class name, and returns an instance of the given class.

useBrick\JsonMapper\JsonMapper;class User{publicfunction__construct(publicint$id,publicstring$name,    ) {    }}$json ='{  "id": 123,  "name": "John Doe"}';$mapper =newJsonMapper();$user =$mapper->map($json, User::class);echo$user->name;// John Doe

JsonMapper will read the parameter types and annotations to map nested objects:

class Album{publicfunction__construct(publicint$id,publicstring$title,publicArtist$artist,    ) {    }}class Artist{publicfunction__construct(publicint$id,publicstring$name,    ) {    }}$json ='{  "id": 456,  "title": "The Wall",  "artist": {    "id": 789,    "name": "Pink Floyd"  }}';$mapper =newJsonMapper();$album =$mapper->map($json, Album::class);echo$album->artist->name;// Pink Floyd

Arrays can be documented with@param annotations, that will be parsed and used to map the JSON data:

class Customer{/**     * @param Address[] $addresses     */publicfunction__construct(publicint$id,publicstring$name,publicarray$addresses,    ) {    }}class Address{publicfunction__construct(publicstring$street,publicstring$city,    ) {    }}$json ='{  "id": 123,  "name": "John Doe",  "addresses": [    {      "street": "123 Main Street",      "city": "New York"    },    {      "street": "456 Side Street",      "city": "New York"    }  ]}';$mapper =newJsonMapper();$customer =$mapper->map($json, Customer::class);foreach ($customer->addressesas$address) {var_export($addressinstanceof Address);// true}

If a parameter is a declared as a union of possible types,JsonMapper will automatically attempt to map the JSON data to the correct type:

class Order{publicfunction__construct(publicreadonlyint$id,publicreadonlystring$amount,publicreadonlyPerson|Company$customer,// union type    ) {    }}class Person{publicfunction__construct(publicreadonlyint$id,publicreadonlystring$firstname,publicreadonlystring$lastname,    ) {    }}class Company{publicfunction__construct(publicreadonlyint$id,publicreadonlystring$name,publicreadonlystring$companyNumber,    ) {    }}$json ='{  "id": 1,  "amount": "24.99",  "customer": {    "id": 2,    "firstname": "John",    "lastname": "Doe"  }}';$mapper =newJsonMapper();$order =$mapper->map($json, Order::class);// JsonMapper automatically determined that the "id", "firstname",// and "lastname" properties correspond to a Person and not a Company.var_export($order->customerinstanceof Person);// true

To achieve this,JsonMapper attempts to map a JSON object to every possible PHP class in the union. If no class matches, or if several classes match, an exception is thrown.

JsonMapper canparse, map, and verify any combination of possibly nested types:

/** * @param (Person|Company|(string|int)[])[]|null $customers */publicfunction__construct(publicreadonly ?array$customers,) {}

This currently comes with two limitations:

• you must use theType[] syntax for arrays, and not thearray<Type> syntax;

• you cannot use more than one array type per union; for example, this is allowed:

  /** * @param (Person|Company)[] $value */

  but this is not:

  /** * @param Person[]|Company[] $value */

JsonMapper can map JSON strings and integers to backed enums:

class Order{publicfunction__construct(publicreadonlyint$id,publicreadonlyOrderStatus$status,    ) {    }}enum OrderStatus:string {casePENDING ='pending';caseSHIPPED ='shipped';caseDELIVERED ='delivered';}$json ='{  "id": 1,  "status": "shipped"}';$mapper =newJsonMapper();$order =$mapper->map($json, Order::class);var_export($order->status === OrderStatus::SHIPPED);// true

Non-backed enums, i.e. enums that do not have astring orint value, are not supported on purpose.

The library has very strict defaults (some of which can be overridden by config), and will throw an exception if the JSON data does not exactly match the DTO's constructor signature, or if the DTO contains invalid or unsupported@param annotations.

The types of the parameters must match exactly, with the same semantics as PHP'sstrict_types.

JsonMapper guarantees that every constructor parameter, even softly-typed with@param, will be passed a value that is compatible with the declared type. The result is a DTO that can be 100% trusted by your static analysis tool.

TheJsonMapper constructor accepts the following options:

• $allowUntypedArrays

  By default,JsonMapper will throw an exception if the parameter is declared asarray without a corresponding@param annotation, or is just documented as@param array.

  By setting this option totrue,JsonMapper will allow such parameters, and accept to pass a JSON array as is, without checking or mapping its contents:

  $mapper =newJsonMapper(    allowUntypedArrays:true,);

• $allowUntypedObjects

  By default,JsonMapper will throw an exception if a parameter is declared asobject orstdClass.

  By setting this option totrue,JsonMapper will allow such parameters, and accept to pass a JSON object as anstdClass instance, without checking or mapping its contents:

  $mapper =newJsonMapper(    allowUntypedObjects:true,);

• $allowMixed

  By default,JsonMapper will throw an exception if a parameter is declared asmixed.

  By setting this option totrue,JsonMapper will allow such parameters, and accept to pass a JSON value as is, without checking or mapping its contents:

  $mapper =newJsonMapper(    allowMixed:true,);

• $onExtraProperties

  This option accepts anOnExtraProperties enum value, and controls howJsonMapper reacts if a JSON object contains a property that does not have a matching parameter in the corresponding DTO's constructor signature:

  • OnExtraProperties::THROW_EXCEPTION

    JsonMapper will throw aJsonMapperException. This is the default value.

  • OnExtraProperties::IGNORE

    JsonMapper will ignore any extra properties:

    useBrick\JsonMapper\JsonMapper;useBrick\JsonMapper\OnExtraProperties;class Order{publicfunction__construct(publicreadonlyint$id,publicreadonlystring$amount,    ) {    }}$json ='{  "id": 1,  "amount": "100.00",  "extraProperty": "foo",  "otherExtraProperty": "bar"}';$mapper =newJsonMapper(    onExtraProperties: OnExtraProperties::IGNORE,);// extra properties "extraProperty" and "otherExtraProperty" are ignored,// and do not throw an exception anymore.$order =$mapper->map($json, Order::class);

• $onMissingProperties

  This option accepts anOnMissingProperties enum value, and controls howJsonMapper reacts if a JSON object is missing a property that is declared in the corresponding DTO's constructor signature:

  • OnMissingProperties::THROW_EXCEPTION

    JsonMapper will throw aJsonMapperException. This is the default value.

  • OnMissingProperties::SET_NULL

    JsonMapper will set the parameter tonull if the JSON property is missing and the parameter is nullable:

    useBrick\JsonMapper\JsonMapper;useBrick\JsonMapper\OnMissingProperties;class Order{publicfunction__construct(publicreadonlyint$id,publicreadonly ?string$customerName,    ) {    }}$json ='{  "id": 1}';$mapper =newJsonMapper(    onMissingProperties: OnMissingProperties::SET_NULL,);$order =$mapper->map($json, Order::class);var_export($order->customerName);// NULL

    If the property is missing and the parameter is not nullable, an exception will be thrown regardless of this option.

  • OnMissingProperties::SET_DEFAULT

    JsonMapper will set the parameter to its default value if the JSON property is missing and the parameter has a default value:

    useBrick\JsonMapper\JsonMapper;useBrick\JsonMapper\OnMissingProperties;class Order{publicfunction__construct(publicreadonlyint$id,publicreadonlystring$customerName ='no name',    ) {    }}$json ='{  "id": 1}';$mapper =newJsonMapper(    onMissingProperties: OnMissingProperties::SET_DEFAULT,);$order =$mapper->map($json, Order::class);var_export($order->customerName);// 'no name'

    If the property is missing and the parameter does not have a default value, an exception will be thrown regardless of this option.

• $jsonToPhpNameMapper &$phpToJsonNameMapper

  By default,JsonMapper assumes that the JSON property names are the same as the PHP parameter names.

  By providing implementations of theNameMapper interface, you can customize the mapping between the two.

  The library comes with two implementations for a common use case:

  • SnakeCaseToCamelCaseMapper will convertsnake_casecamelCase
  • CamelCaseToSnakeCaseMapper will convertcamelCase tosnake_case

  Example:

  useBrick\JsonMapper\JsonMapper;useBrick\JsonMapper\NameMapper\CamelCaseToSnakeCaseMapper;useBrick\JsonMapper\NameMapper\SnakeCaseToCamelCaseMapper;class Order{publicfunction__construct(publicreadonlyint$id,publicreadonlyint$amountInCents,publicreadonlystring$customerName,    ) {    }}$json ='{  "id": 1,  "amount_in_cents": 2499,  "customer_name": "John Doe"}';$mapper =newJsonMapper(    jsonToPhpNameMapper:newSnakeCaseToCamelCaseMapper(),    phpToJsonNameMapper:newCamelCaseToSnakeCaseMapper(),);$order =$mapper->map($json, Order::class);echo$order->amountInCents;// 2499echo$order->customerName;// 'John Doe'