PHPackages                             tiny-blocks/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. tiny-blocks/mapper

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

tiny-blocks/mapper
==================

Maps PHP objects to and from arrays, JSON, and iterables through reflection and pluggable strategies.

3.1.0(3w ago)22.0k↓82.6%6MITPHPPHP ^8.5CI passing

Since Dec 24Pushed 3w ago2 watchersCompare

[ Source](https://github.com/tiny-blocks/mapper)[ Packagist](https://packagist.org/packages/tiny-blocks/mapper)[ Docs](https://github.com/tiny-blocks/mapper)[ RSS](/packages/tiny-blocks-mapper/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (15)Versions (20)Used By (6)

Mapper
======

[](#mapper)

[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](https://github.com/tiny-blocks/mapper/blob/main/LICENSE)

- [Overview](#overview)
- [Installation](#installation)
- [How to use](#how-to-use)
    - [The Mapper service](#the-mapper-service)
    - [The Mappable trait](#the-mappable-trait)
    - [Polymorphic types with Subtype](#polymorphic-types-with-subtype)
    - [Flat rows with Layout](#flat-rows-with-layout)
    - [JSON columns with JsonColumn](#json-columns-with-jsoncolumn)
    - [Collections that map themselves](#collections-that-map-themselves)
    - [Scalar codecs with Codec](#scalar-codecs-with-codec)
    - [Self-describing scalars with ScalarCodec](#self-describing-scalars-with-scalarcodec)
    - [Transparent delegation for single-property wrappers](#transparent-delegation-for-single-property-wrappers)
    - [Preserving object shape with Structured](#preserving-object-shape-with-structured)
    - [Factory construction with FactoryMethod](#factory-construction-with-factorymethod)
    - [Configuration and naming](#configuration-and-naming)
    - [Exceptions](#exceptions)
- [License](#license)
- [Contributing](#contributing)

Overview
--------

[](#overview)

Maps PHP objects to and from arrays, JSON, and iterables through reflection and pluggable strategies. Handles backed and pure enums, value objects, nested objects, date-time types, and collections out of the box. Designed for DTO hydration, serialization at the HTTP boundary, flat-row decoding at the persistence boundary, and data transfer between bounded contexts.

The library exposes two complementary ways to use it. The primary one is the `Mapper` service, an immutable builder that keeps the mapped class fully decoupled from the library. No interface to implement, no trait to use, nothing on the domain side. It fulfills two narrow service contracts, `Serializer` (object to array and JSON) and `Deserializer` (array, JSON, or iterable to object), so a consumer can depend on the capability it needs rather than on the concrete service.

The second is the `Mappable` interface plus the `MappableBehavior` trait, an opt-in hook for application DTOs that prefer to map themselves. `Mappable` combines `Serializable` (render to array and JSON) and `Deserializable` (build from a source). The mapping logic lives in the mapper, not on the type: objects are reflected by the engine and collections are built internally, so a `Mappable` type exposes no engine-facing method. When a configured `Mapper` maps a `Mappable` value, the engine reflects it through the active naming, so nested children resolve through any registered mappings.

Installation
------------

[](#installation)

```
composer require tiny-blocks/mapper
```

How to use
----------

[](#how-to-use)

### The Mapper service

[](#the-mapper-service)

`Mapper::create()` returns an empty mapper with identity naming and lenient unknown keys. The same instance hydrates from arrays, JSON strings, and iterables, and serializes back to arrays or JSON.

A currency-bearing amount is the value object the mapper hydrates.

```