PHPackages                             brick/json-mapper - 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. [Parsing & Serialization](/categories/parsing)
4. /
5. brick/json-mapper

ActiveLibrary[Parsing & Serialization](/categories/parsing)

brick/json-mapper
=================

Maps JSON data to strongly typed PHP DTOs

0.2.1(3mo ago)20552.1k↓23.9%10[4 PRs](https://github.com/brick/json-mapper/pulls)2MITPHPPHP ^8.2CI passing

Since Feb 15Pushed 2mo ago7 watchersCompare

[ Source](https://github.com/brick/json-mapper)[ Packagist](https://packagist.org/packages/brick/json-mapper)[ GitHub Sponsors](https://github.com/BenMorel)[ RSS](/packages/brick-json-mapper/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (4)Versions (6)Used By (2)

Brick\\JsonMapper
=================

[](#brickjsonmapper)

[![](https://raw.githubusercontent.com/brick/brick/master/logo.png)](https://raw.githubusercontent.com/brick/brick/master/logo.png)

Maps JSON data to strongly typed PHP DTOs.

[![Build Status](https://github.com/brick/json-mapper/workflows/CI/badge.svg)](https://github.com/brick/json-mapper/actions)[![Coverage Status](https://camo.githubusercontent.com/db71f27125d5eb42a9c3bf599364ed2b51481f776bd8f79a36f00d913c066228/68747470733a2f2f636f6465636f762e696f2f6769746875622f627269636b2f6a736f6e2d6d61707065722f67726170682f62616467652e737667)](https://codecov.io/github/brick/json-mapper)[![Latest Stable Version](https://camo.githubusercontent.com/f1bdaa6b0413ffee9ab52be43729c4e8eda90e80d1b1e1e0a02c450eed2449ec/68747470733a2f2f706f7365722e707567782e6f72672f627269636b2f6a736f6e2d6d61707065722f762f737461626c65)](https://packagist.org/packages/brick/json-mapper)[![Total Downloads](https://camo.githubusercontent.com/f4f99c103780908fc53473fb8794e6b2bfa3e629778e0c95bc02072420182c47/68747470733a2f2f706f7365722e707567782e6f72672f627269636b2f6a736f6e2d6d61707065722f646f776e6c6f616473)](https://packagist.org/packages/brick/json-mapper)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](http://opensource.org/licenses/MIT)

Introduction
------------

[](#introduction)

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.

### Installation

[](#installation)

This library is installable via [Composer](https://getcomposer.org/):

```
composer require brick/json-mapper
```

### Requirements

[](#requirements)

This library requires PHP 8.2 or later.

### Project status & release process

[](#project-status--release-process)

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

The current releases are numbered `0.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 new `0.x` version cycle is always started.**

It is therefore safe to lock your project to a given release cycle, such as `0.1.*`.

If you need to upgrade to a newer release cycle, check the [release history](https://github.com/brick/json-mapper/releases) for a list of changes introduced by each further `0.x.0` version.

Usage
-----

[](#usage)

### Basic usage

[](#basic-usage)

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

```
use Brick\JsonMapper\JsonMapper;

class User
{
    public function __construct(
        public int $id,
        public string $name,
    ) {
    }
}

$json = '{
  "id": 123,
  "name": "John Doe"
}';

$mapper = new JsonMapper();
$user = $mapper->map($json, User::class);

echo $user->name; // John Doe
```

### Nested objects

[](#nested-objects)

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

```
class Album
{
    public function __construct(
        public int $id,
        public string $title,
        public Artist $artist,
    ) {
    }
}

class Artist
{
    public function __construct(
        public int $id,
        public string $name,
    ) {
    }
}

$json = '{
  "id": 456,
  "title": "The Wall",
  "artist": {
    "id": 789,
    "name": "Pink Floyd"
  }
}';

$mapper = new JsonMapper();
$album = $mapper->map($json, Album::class);

echo $album->artist->name; // Pink Floyd
```

### Arrays

[](#arrays)

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

```
class Customer
{
    /**
     * @param Address[] $addresses
     */
    public function __construct(
        public int $id,
        public string $name,
        public array $addresses,
    ) {
    }
}

class Address
{
    public function __construct(
        public string $street,
        public string $city,
    ) {
    }
}

$json = '{
  "id": 123,
  "name": "John Doe",
  "addresses": [
    {
      "street": "123 Main Street",
      "city": "New York"
    },
    {
      "street": "456 Side Street",
      "city": "New York"
    }
  ]
}';

$mapper = new JsonMapper();
$customer = $mapper->map($json, Customer::class);

foreach ($customer->addresses as $address) {
    var_export($address instanceof Address); // true
}
```

### Union types

[](#union-types)

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
{
    public function __construct(
        public readonly int $id,
        public readonly string $amount,
        public readonly Person|Company $customer, // union type
    ) {
    }
}

class Person
{
    public function __construct(
        public readonly int $id,
        public readonly string $firstname,
        public readonly string $lastname,
    ) {
    }
}

class Company
{
    public function __construct(
        public readonly int $id,
        public readonly string $name,
        public readonly string $companyNumber,
    ) {
    }
}

$json = '{
  "id": 1,
  "amount": "24.99",
  "customer": {
    "id": 2,
    "firstname": "John",
    "lastname": "Doe"
  }
}';

$mapper = new JsonMapper();
$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->customer instanceof 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.

### Complex unions

[](#complex-unions)

`JsonMapper` can **parse, map, and verify** any combination of possibly nested types:

```
/**
 * @param (Person|Company|(string|int)[])[]|null $customers
 */
public function __construct(
    public readonly ?array $customers,
) {
}
```

This currently comes with two limitations:

- you must use the `Type[]` syntax for arrays, and not the `array` 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
     */
    ```

### Enums

[](#enums)

`JsonMapper` can map JSON strings and integers to backed enums:

```
class Order
{
    public function __construct(
        public readonly int $id,
        public readonly OrderStatus $status,
    ) {
    }
}

enum OrderStatus: string {
    case PENDING = 'pending';
    case SHIPPED = 'shipped';
    case DELIVERED = 'delivered';
}

$json = '{
  "id": 1,
  "status": "shipped"
}';

$mapper = new JsonMapper();
$order = $mapper->map($json, Order::class);

var_export($order->status === OrderStatus::SHIPPED); // true
```

Non-backed enums, i.e. enums that do not have a `string` or `int` value, are not supported on purpose.

### Strictness

[](#strictness)

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's `strict_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.

### Options

[](#options)

The `JsonMapper` constructor accepts the following options:

- **`$allowUntypedArrays`**

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

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

    ```
    $mapper = new JsonMapper(
        allowUntypedArrays: true,
    );
    ```
- **`$allowUntypedObjects`**

    By default, `JsonMapper` will throw an exception if a parameter is declared as `object` or `stdClass`.

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

    ```
    $mapper = new JsonMapper(
        allowUntypedObjects: true,
    );
    ```
- **`$allowMixed`**

    By default, `JsonMapper` will throw an exception if a parameter is declared as `mixed`.

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

    ```
    $mapper = new JsonMapper(
        allowMixed: true,
    );
    ```
- **`$onExtraProperties`**

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

    - **`OnExtraProperties::ThrowException`**

        `JsonMapper` will throw a `JsonMapperException`. This is the default value.
    - **`OnExtraProperties::Ignore`**

        `JsonMapper` will ignore any extra properties:

        ```
        use Brick\JsonMapper\JsonMapper;
        use Brick\JsonMapper\OnExtraProperties;

        class Order
        {
            public function __construct(
                public readonly int $id,
                public readonly string $amount,
            ) {
            }
        }

        $json = '{
          "id": 1,
          "amount": "100.00",
          "extraProperty": "foo",
          "otherExtraProperty": "bar"
        }';

        $mapper = new JsonMapper(
            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 an `OnMissingProperties` enum value, and controls how `JsonMapper` reacts if a JSON object is missing a property that is declared in the corresponding DTO's constructor signature:

    - **`OnMissingProperties::ThrowException`**

        `JsonMapper` will throw a `JsonMapperException`. This is the default value.
    - **`OnMissingProperties::SetNull`**

        `JsonMapper` will set the parameter to `null` if the JSON property is missing and the parameter is nullable:

        ```
        use Brick\JsonMapper\JsonMapper;
        use Brick\JsonMapper\OnMissingProperties;

        class Order
        {
            public function __construct(
                public readonly int $id,
                public readonly ?string $customerName,
            ) {
            }
        }

        $json = '{
          "id": 1
        }';

        $mapper = new JsonMapper(
            onMissingProperties: OnMissingProperties::SetNull,
        );

        $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::SetDefault`**

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

        ```
        use Brick\JsonMapper\JsonMapper;
        use Brick\JsonMapper\OnMissingProperties;

        class Order
        {
            public function __construct(
                public readonly int $id,
                public readonly string $customerName = 'no name',
            ) {
            }
        }

        $json = '{
          "id": 1
        }';

        $mapper = new JsonMapper(
            onMissingProperties: OnMissingProperties::SetDefault,
        );

        $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 the `NameMapper` interface, you can customize the mapping between the two.

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

    - `SnakeCaseToCamelCaseMapper` will convert `snake_case` `camelCase`
    - `CamelCaseToSnakeCaseMapper` will convert `camelCase` to `snake_case`

    Example:

    ```
    use Brick\JsonMapper\JsonMapper;
    use Brick\JsonMapper\NameMapper\CamelCaseToSnakeCaseMapper;
    use Brick\JsonMapper\NameMapper\SnakeCaseToCamelCaseMapper;

    class Order
    {
        public function __construct(
            public readonly int $id,
            public readonly int $amountInCents,
            public readonly string $customerName,
        ) {
        }
    }

    $json = '{
      "id": 1,
      "amount_in_cents": 2499,
      "customer_name": "John Doe"
    }';

    $mapper = new JsonMapper(
        jsonToPhpNameMapper: new SnakeCaseToCamelCaseMapper(),
        phpToJsonNameMapper: new CamelCaseToSnakeCaseMapper(),
    );

    $order = $mapper->map($json, Order::class);

    echo $order->amountInCents; // 2499
    echo $order->customerName; // 'John Doe'
    ```

###  Health Score

55

—

FairBetter than 98% of packages

Maintenance86

Actively maintained with recent releases

Popularity48

Moderate usage in the ecosystem

Community21

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 96% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~365 days

Total

4

Last Release

90d ago

PHP version history (2 changes)0.1.0PHP ^8.1

0.2.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/57189121968030f0770811b461cc92f9c19c08f5c4767292f2ede48b7277cfad?d=identicon)[BenMorel](/maintainers/BenMorel)

---

Top Contributors

[![BenMorel](https://avatars.githubusercontent.com/u/1952838?v=4)](https://github.com/BenMorel "BenMorel (48 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (1 commits)")[![skmedix](https://avatars.githubusercontent.com/u/3246162?v=4)](https://github.com/skmedix "skmedix (1 commits)")

---

Tags

jsonbrickmapperdto

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/brick-json-mapper/health.svg)

```
[![Health](https://phpackages.com/badges/brick-json-mapper/health.svg)](https://phpackages.com/packages/brick-json-mapper)
```

###  Alternatives

[justinrainbow/json-schema

A library to validate a json schema.

3.6k316.9M612](/packages/justinrainbow-json-schema)[mtdowling/jmespath.php

Declaratively specify how to extract elements from a JSON document

2.0k472.8M135](/packages/mtdowling-jmespathphp)[jms/serializer

Library for (de-)serializing data of any complexity; supports XML, and JSON.

2.3k135.8M851](/packages/jms-serializer)[jms/serializer-bundle

Allows you to easily serialize, and deserialize data of any complexity

1.8k89.3M627](/packages/jms-serializer-bundle)[json-mapper/json-mapper

Map JSON structures to PHP classes

2181.1M22](/packages/json-mapper-json-mapper)[colinodell/json5

UTF-8 compatible JSON5 parser for PHP

30422.2M45](/packages/colinodell-json5)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)