tiny-blocks/mapper

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

2.0.4 2026-04-21 21:57 UTC

Requires

• php: ^8.5

Requires (Dev)

• ergebnis/composer-normalize: ^2.51
• infection/infection: ^0.32
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^13.1
• squizlabs/php_codesniffer: ^4.0

MIT

• Gustavo Freze de Araujo Santos

README

• Overview
• Installation
• How to use
• License
• Contributing

Overview

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

Installation

composer require tiny-blocks/mapper

How to use

The examples demonstrate how to create objects from iterables, map objects to arrays, and convert objects to JSON.

Create an object from an iterable

First, define your classes using the ObjectMapper interface and ObjectMappability trait:

<?php

declare(strict_types=1);

namespace Example;

use TinyBlocks\Mapper\ObjectMappability;
use TinyBlocks\Mapper\ObjectMapper;

final readonly class ShippingAddress implements ObjectMapper
{
    use ObjectMappability;

    public function __construct(
        private string $city,
        private ShippingState $state,
        private string $street,
        private int $number,
        private ShippingCountry $country
    ) {
    }
}

Next, define a collection class implementing IterableMapper:

<?php

declare(strict_types=1);

namespace Example;

use TinyBlocks\Collection\Collection;
use TinyBlocks\Mapper\IterableMappability;
use TinyBlocks\Mapper\IterableMapper;

final class ShippingAddresses extends Collection implements IterableMapper
{
    use IterableMappability;

    public function getType(): string
    {
        return ShippingAddress::class;
    }
}

Finally, create a class that uses the collection:

<?php

declare(strict_types=1);

namespace Example;

use TinyBlocks\Mapper\ObjectMappability;
use TinyBlocks\Mapper\ObjectMapper;

final readonly class Shipping implements ObjectMapper
{
    use ObjectMappability;

    public function __construct(public int $id, public ShippingAddresses $addresses)
    {
    }
}

Now you can map data into a Shipping object using fromIterable:

<?php

use Example\Shipping;

$shipping = Shipping::fromIterable(iterable: [
    'id'        => PHP_INT_MAX,
    'addresses' => [
        [
            'city'    => 'New York',
            'state'   => 'NY',
            'street'  => '5th Avenue',
            'number'  => 717,
            'country' => 'US'
        ]
    ]
]);

Map object to array

Once the object is created, you can easily convert it into an array representation.

$shipping->toArray();

This will output the following array:

[
    'id'        => 9223372036854775807,
    'addresses' => [
        [
            'city'    => 'New York',
            'state'   => 'NY',
            'street'  => '5th Avenue',
            'number'  => 717,
            'country' => 'US'
        ]
    ]
]

Map object to JSON

Similarly, you can convert the object into a JSON representation.

$shipping->toJson();

This will produce the following JSON:

{
    "id": 9223372036854775807,
    "addresses": [
        {
            "city": "New York",
            "state": "NY",
            "street": "5th Avenue",
            "number": 717,
            "country": "US"
        }
    ]
}

License

Mapper is licensed under MIT.

Contributing

Please follow the contributing guidelines to contribute to the project.