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().
Installation
Section titled “Installation”composer require type-lang/mapperRequirements:
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) }Objects
Section titled “Objects”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' }$mapper->denormalize(['id' => 'abc', 'name' => 'Alice'], User::class);// throws InvalidValueException:// $.id: Value must be of type int, but "abc" given$mapper->denormalize(['id' => 42], User::class);// throws InvalidValueException: $.name: Required field "name" is missingNested objects
Section titled “Nested objects”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' } }$mapper->denormalize(['from' => 'Paris'], Trip::class);// throws InvalidValueException:// $.from: Value must be of type object{name: string}, but "Paris" given$mapper->denormalize(['from' => ['name' => null]], Trip::class);// throws InvalidValueException:// $.from.name: Value must be of type string, but null givenThe 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' }] }$mapper->denormalize([ 'stops' => [['name' => 'Paris'], 'Berlin'],], Route::class);// throws InvalidValueException:// $.stops[1]: Value must be of type object{name: string},// but "Berlin" given$mapper->denormalize([ 'stops' => ['a' => ['name' => 'Paris']],], Route::class);// throws InvalidValueException:// $.stops: Value must be of type list<object{name: string}>,// but array(1) givenRefined types
Section titled “Refined types”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' }$mapper->denormalize(['id' => -1, 'name' => 'Alice'], User::class);// throws InvalidValueException:// $.id: Value must be of type positive-int (>= 1)$mapper->denormalize(['id' => 42, 'name' => ''], User::class);// throws InvalidValueException:// $.name: Value must be of type non-empty-string (non-empty)Optional fields
Section titled “Optional fields”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 }$mapper->denormalize(['role' => 'admin'], Account::class);// throws InvalidValueException: $.email: Required field "email" is missingEnums and dates
Section titled “Enums and dates”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'),// }$mapper->denormalize([ 'role' => 'root', 'createdAt' => '2026-01-15T10:00:00+00:00',], Member::class);// throws InvalidValueException:// $.role: Value must be of type 'admin'|'member', but "root" givenType coercion
Section titled “Type coercion”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" givenNormalization
Section titled “Normalization”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']Any type
Section titled “Any type”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'Checking without exceptions
Section titled “Checking without exceptions”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);// falseSee errors for the exceptions and their messages.
What’s next
Section titled “What’s next”- 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