PHPackages                             magicsunday/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. magicsunday/jsonmapper

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

magicsunday/jsonmapper
======================

Map JSON to PHP

3.0.4(2mo ago)29.1k↓41.7%12MITPHPPHP ^8.3CI passing

Since Jan 28Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/magicsunday/jsonmapper)[ Packagist](https://packagist.org/packages/magicsunday/jsonmapper)[ Fund](https://paypal.me/magicsunday)[ RSS](/packages/magicsunday-jsonmapper/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (26)Versions (32)Used By (2)

JsonMapper: JSON to PHP Object Mapping
======================================

[](#jsonmapper-json-to-php-object-mapping)

 Map JSON data to strongly-typed PHP classes using Symfony's PropertyInfo and PropertyAccess components.

 [![CI](https://github.com/magicsunday/jsonmapper/actions/workflows/ci.yml/badge.svg)](https://github.com/magicsunday/jsonmapper/actions/workflows/ci.yml)

 [![PHPStan Max Level](https://camo.githubusercontent.com/ecb39a33957e802f1f085f1debada1e99904e72b8d807e98991fb7f9660cb6d3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6d61782532306c6576656c2d627269676874677265656e2e737667)](https://phpstan.org/) [![PHPUnit 12](https://camo.githubusercontent.com/d35eb3ecb6eed79465d7c45a056b1dd1a739602a5b5597578fed9564b65e9e2d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f504850556e69742d31322d626c75652e737667)](https://phpunit.de/) [![Rector 2.0](https://camo.githubusercontent.com/9e64e770b8b919b97683d84fefdff21986835b3c8e9afbe5f5e23c9668668315/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f526563746f722d322e302d6f72616e67652e737667)](https://getrector.com/) [![PSR-12](https://camo.githubusercontent.com/34b10db0caa29bacd49bda5c437a8de95385f036f3230b31fa605326e18da22c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f436f64652532305374796c652d5053522d2d31322d626c75652e737667)](https://www.php-fig.org/psr/psr-12/)

 [![PHP Version](https://camo.githubusercontent.com/6efe0674150d2035887c1de2bcea38890ebe3b2c203bbaa7d9e0550a10308948/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e337c382e347c382e352d626c7565)](composer.json)

 [![Latest version](https://camo.githubusercontent.com/19bdc552d092ea0106f1b292e84dd50a704059b5a2292231f65b4d7e1c06ac48/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6d6167696373756e6461792f6a736f6e6d61707065723f736f72743d73656d766572)](https://github.com/magicsunday/jsonmapper/releases/latest) [![License](https://camo.githubusercontent.com/230fe6b6ae3f3e2f387664fee4fd0563540197b62239a4e96ac44bcb367adcc4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6d6167696373756e6461792f6a736f6e6d6170706572)](LICENSE)

---

📌 Overview
----------

[](#-overview)

JsonMapper is a PHP library that maps JSON data to strongly-typed PHP classes (DTOs, value objects, entities) using reflection and PHPDoc annotations. It leverages Symfony's PropertyInfo and PropertyAccess components to provide flexible, extensible JSON-to-PHP object mapping.

KeyValuePackage`magicsunday/jsonmapper`PHP`^8.3`Main API`MagicSunday\JsonMapper`OutputMapped PHP objects + optional `MappingReport`❓ What is this?
---------------

[](#-what-is-this)

JsonMapper takes decoded JSON (via `json_decode`) and hydrates typed PHP objects, including nested objects, collections, enums, DateTime values, and custom types. It supports both lenient and strict mapping modes with detailed error reporting.

🎯 Why does this exist?
----------------------

[](#-why-does-this-exist)

Mapping API responses or configuration payloads to typed PHP classes is a common task that involves repetitive boilerplate. JsonMapper automates this with a clean, extensible architecture based on Symfony components, supporting advanced scenarios like polymorphic APIs, custom name conversion, and recursive collection handling.

🚀 Usage
-------

[](#-usage)

```
composer require magicsunday/jsonmapper
```

### Quick start

[](#quick-start)

```
namespace App\Dto;

use ArrayObject;

final class Comment
{
    public string $message;
}

/**
 * @extends ArrayObject
 */
final class CommentCollection extends ArrayObject
{
}

/**
 * @extends ArrayObject
 */
final class ArticleCollection extends ArrayObject
{
}

final class Article
{
    public string $title;

    /**
     * @var CommentCollection
     */
    public CommentCollection $comments;
}
```

```
require __DIR__ . '/vendor/autoload.php';

use App\Dto\Article;
use App\Dto\ArticleCollection;
use MagicSunday\JsonMapper;

$single = json_decode('{"title":"Hello world","comments":[{"message":"First!"}]}', associative: false, flags: JSON_THROW_ON_ERROR);
$list = json_decode('[{"title":"Hello world","comments":[{"message":"First!"}]},{"title":"Second","comments":[]}]', associative: false, flags: JSON_THROW_ON_ERROR);

$mapper = JsonMapper::createWithDefaults();

$article = $mapper->map($single, Article::class);
$articles = $mapper->map($list, Article::class, ArticleCollection::class);
```

`JsonMapper::createWithDefaults()` wires the default Symfony `PropertyInfoExtractor` (reflection + PhpDoc) and a `PropertyAccessor`. For custom extractors, caching, or a specialised accessor see [Manual instantiation](docs/recipes/manual-instantiation.md).

### PHP classes

[](#php-classes)

Annotate all properties with the requested type. For collections, use the phpDocumentor collection annotation type:

```
/** @var SomeCollection $dates */
/** @var SomeCollection $labels */
/** @var Collection\\SomeCollection $entities */
```

📚 Documentation
---------------

[](#-documentation)

- [API reference](docs/API.md)
- Recipes
    - [Manual instantiation](docs/recipes/manual-instantiation.md) — custom extractors, name converters, class maps, collection mapping
    - [Type converters and custom class maps](docs/recipes/type-converters.md) — custom type handlers, runtime class resolution
    - [Error handling strategies](docs/recipes/error-handling.md) — strict vs. lenient mode, error collection
    - [Performance hints](docs/recipes/performance.md) — PSR-6 type caching
    - [Using mapper attributes](docs/recipes/using-attributes.md) — ReplaceProperty, ReplaceNullWithDefaultValue
    - [Mapping JSON to PHP enums](docs/recipes/mapping-with-enums.md)
    - [Mapping nested collections](docs/recipes/nested-collections.md)
    - [Using a custom name converter](docs/recipes/custom-name-converter.md)

🛠️ Development
--------------

[](#️-development)

Prerequisites:

- PHP `^8.3`
- Extensions: `json`

Install dependencies:

```
composer install
```

Run the mandatory quality gate:

```
composer ci:test
```

`ci:test` includes:

- Linting (`phplint`)
- Unit tests (`phpunit`)
- Static analysis (`phpstan`)
- Refactoring dry-run (`rector --dry-run`)
- Coding standards dry-run (`php-cs-fixer --dry-run`)
- Copy/paste detection (`jscpd`)

🤝 Contributing
--------------

[](#-contributing)

See `CONTRIBUTING.md` for contributor workflow and minimal setup.

If contributions are prepared or modified by an LLM/agent, follow `AGENTS.md`.

###  Health Score

56

—

FairBetter than 98% of packages

Maintenance85

Actively maintained with recent releases

Popularity29

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity79

Established project with proven stability

 Bus Factor1

Top contributor holds 98.1% 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 ~71 days

Recently: every ~0 days

Total

27

Last Release

76d ago

Major Versions

1.6 → 2.02021-12-16

2.4.0 → 3.0.02025-11-14

2.x-dev → 3.0.32026-03-03

PHP version history (10 changes)1.0PHP ^7.4

1.1PHP ^7.4 || ^8.0

2.1.2PHP ~7.3.0

2.2.4PHP >=7.4.0 <8.1.0

2.3.0PHP >=8.1.0 <8.4.0

2.4.0PHP >=8.2.0 <8.5.0

3.0.0PHP >=8.3.0 <8.5.0

3.0.1PHP >=8.3.0 <8.6.0

3.0.2PHP ^8.3

2.4.1PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/1979dde7200fccc0e21e18a29b5566f22fa01ad104e577254fe74e14ae04a297?d=identicon)[magicsunday](/maintainers/magicsunday)

---

Top Contributors

[![magicsunday](https://avatars.githubusercontent.com/u/564393?v=4)](https://github.com/magicsunday "magicsunday (153 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (2 commits)")[![CybotTM](https://avatars.githubusercontent.com/u/326348?v=4)](https://github.com/CybotTM "CybotTM (1 commits)")

---

Tags

jsonjsonmappermapperphp

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/magicsunday-jsonmapper/health.svg)

```
[![Health](https://phpackages.com/badges/magicsunday-jsonmapper/health.svg)](https://phpackages.com/packages/magicsunday-jsonmapper)
```

###  Alternatives

[api-platform/core

Build a fully-featured hypermedia or GraphQL API in minutes!

2.6k48.1M236](/packages/api-platform-core)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[symfony/ai-platform

PHP library for interacting with AI platform provider.

51927.7k136](/packages/symfony-ai-platform)[api-platform/metadata

API Resource-oriented metadata attributes and factories

223.5M96](/packages/api-platform-metadata)[cognesy/instructor-php

The complete AI toolkit for PHP: unified LLM API, structured outputs, agents, and coding agent control

310107.9k1](/packages/cognesy-instructor-php)

PHPackages © 2026

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