Skip to content

Overview

Type mapper

A mapper converts data by a type in both directions:

  • Denormalization — external data (decoded JSON, a form, a database row) into PHP values: objects, enums, dates, typed lists.
  • Normalization — PHP values back into plain data (scalars, arrays) ready for json_encode().
composer require type-lang/mapper

Requirements:

  • PHP >= 8.1
$mapper = new TypeLang\Mapper\Mapper();
$array = $mapper->normalize(new Example());
// ['key' => 42, ...]
$object = $mapper->denormalize($array, Example::class);
// object(Example) { key: int(42) }

A class is mapped by its public properties and their native types, nothing has to be configured:

final class User
{
public int $id;
public string $name;
}

Data that does not match the class is rejected with the path of the wrong value:

$mapper->denormalize(['id' => 42, 'name' => 'Alice'], User::class);
// User { id: 42, name: 'Alice' }

A property of a class type is mapped the same way, to any depth:

final class City
{
public string $name;
}
final class Trip
{
public City $from;
}
$mapper->denormalize(['from' => ['name' => 'Paris']], Trip::class);
// Trip { from: City { name: 'Paris' } }

The native array says nothing about its elements: such a property takes any array as it is. The type of the elements is given by @var:

final class Route
{
/**
* @var list<City>
*/
public array $stops;
}

Both the list and each of its elements are checked:

$mapper->denormalize([
'stops' => [['name' => 'Paris'], ['name' => 'Berlin']],
], Route::class);
// Route { stops: [City { name: 'Paris' }, City { name: 'Berlin' }] }

A PHPDoc type may be stricter than the native one. Any of the supported types can be used:

final class User
{
/**
* @var positive-int
*/
public int $id;
/**
* @var non-empty-string
*/
public string $name;
}
$mapper->denormalize(['id' => 42, 'name' => 'Alice'], User::class);
// User { id: 42, name: 'Alice' }

A property with a default value is optional. A nullable property without a default one still has to be given:

final class Account
{
public string $role = 'member';
public ?string $email;
}
$mapper->denormalize(['email' => null], Account::class);
// Account { role: 'member', email: null }

A backed enum is mapped by its value, a date by a string:

enum Role: string
{
case Admin = 'admin';
case Member = 'member';
}
final class Member
{
public Role $role;
public DateTimeImmutable $createdAt;
}
$mapper->denormalize([
'role' => 'admin',
'createdAt' => '2026-01-15T10:00:00+00:00',
], Member::class);
// Member {
// role: Role::Admin,
// createdAt: DateTimeImmutable('2026-01-15T10:00:00+00:00'),
// }

A value written in another form is converted when it is the same value, as in data of a form or a query string. See type coercion for the rules and the strict mode.

$mapper->denormalize('42', 'int'); // 42
$mapper->denormalize('4.2', 'int');
// throws InvalidValueException: $: Value must be of type int, but "4.2" given

normalize() converts a value back into plain data by the same types:

$member = $mapper->denormalize([
'role' => 'admin',
'createdAt' => '2026-01-15T10:00:00+00:00',
], Member::class);
$mapper->normalize($member);
// ['role' => 'admin', 'createdAt' => '2026-01-15T10:00:00+00:00']

The type is not only a class, but any of the supported types:

$mapper->denormalize('42', 'int');
// 42
$mapper->denormalize([['id' => 1, 'name' => 'Alice']], 'list<User>');
// [User { id: 1, name: 'Alice' }]
$mapper->denormalize(['page' => '2'], 'array{page: positive-int, size?: int}');
// ['page' => 2]
$mapper->denormalize('auto', 'int|"auto"');
// 'auto'

isDenormalizable() and isNormalizable() return whether a value can be converted, without throwing on invalid data:

$mapper->isDenormalizable(['id' => 42, 'name' => 'Alice'], User::class);
// true
$mapper->isDenormalizable(['id' => 'abc', 'name' => 'Alice'], User::class);
// false

See errors for the exceptions and their messages.

  • Configuration — options of the mapper
  • Metadata — how classes are mapped and where it is described
  • Types — all supported types
  • Type Coercion — which values are converted
  • Errors — exceptions and messages
  • Extending — how the mapper works, custom types, decorators, hooks, instantiators, property accessors
  • PHPStan — static analysis of type strings