Skip to content

Integrations

Laravel

The service provider registers mappers in the container of a Laravel 10+ application. It is discovered automatically.

composer require type-lang/mapper-laravel
php artisan vendor:publish --tag=type-lang-mapper-config

The default mapper is the type-lang.mapper singleton, bound to MapperInterface, DenormalizerInterface and NormalizerInterface.

use TypeLang\Mapper\MapperInterface;
final class CreateUserController
{
public function __invoke(Request $req, MapperInterface $mapper): Response
{
$user = $mapper->denormalize($req->all(), UserRequestDTO::class);
// ...
}
}

A named mapper takes the settings of the default one and overrides some of them. There may be any number of them, each is the type-lang.mapper.<name> singleton.

config/type-lang-mapper.php
return [
// settings of the default mapper, inherited by the named ones
'naming' => 'snake_case',
'mappers' => [
// type-lang.mapper.api: config overrides
'api' => [
'strict' => true,
],
// type-lang.mapper.import: config overrides
'import' => [
'reject_extra_fields' => true,
'max_violations' => 100,
],
],
];
app('type-lang.mapper.api')->denormalize('42', 'int');
// throws InvalidValueException: $: Value must be of type int, but "42" given
// to a class
$this->app->when(ApiController::class)
->needs(DenormalizerInterface::class)
->give('type-lang.mapper.api');
config/type-lang-mapper.php
return [
// see "Configuration" for the meaning of the options
'strict' => false,
'normalize_as_array' => true,
'max_violations' => 1,
'reject_extra_fields' => false,
'expected_type_depth' => 1,
'expected_type_max_fields' => null,
// snake_case, camelCase, PascalCase, SCREAMING_SNAKE_CASE, kebab-case
// or a NamingStrategyInterface service
'naming' => null,
// services, see "Extensions"
'types' => [],
'decorators' => [],
'expanders' => [],
'hooks' => [],
'instantiators' => [],
'accessors' => [],
// CoercerInterface service by the type: int, float, string, bool, array
'coercers' => [
'float' => App\Mapper\DecimalCommaCoercer::class,
],
// ViolationFormatterInterface service by the direction:
// denormalization, normalization
'formatters' => [
'denormalization' => App\Mapper\TranslatedFormatter::class,
],
'metadata' => [
// MetadataReaderInterface services over the default readers
'readers' => [],
// config files or directories of them (yaml, yml, neon, json, php)
'paths' => [config_path('mapping')],
// PropertySelectorInterface service
'selector' => null,
'cache' => [
// default = false with "app.debug", true otherwise
'enabled' => null,
// from the first one checked to the last one,
// default = the default cache store
'stores' => [
['store' => 'redis', 'prefix' => 'hot_'],
'file',
],
],
],
// named mappers extending the default one: any number of them, each
// under its own name, with any of the options above it overrides
'mappers' => [
'your_mapper_name' => [
// config overrides
'strict' => true,
],
'another_mapper_name' => [
// config overrides
'naming' => 'camelCase',
'types' => [App\Mapper\MoneyTypeBuilder::class],
],
],
'profiler' => [
// default = enabled with the Debugbar
'debugbar' => null,
// default = enabled with Telescope
'telescope' => null,
],
];

The options are described in Configuration, Naming Strategy, Config Files and Caching. The prefix of the cache keys is tlm_<mapper>_ by default.

An extension is a class name or a container id, resolved with the container.

config/type-lang-mapper.php
return [
'types' => [App\Mapper\UuidTypeBuilder::class],
'hooks' => ['app.mapper.audit_hook'],
'mappers' => [
'api' => [
'types' => [App\Mapper\MoneyTypeBuilder::class],
],
],
];
Config key Interface
types TypeBuilderInterface
decorators TypeDecoratorInterface
expanders TypeExpanderInterface
hooks ClassHookInterface
instantiators InstantiationStrategyInterface
accessors AccessStrategyInterface
metadata.readers MetadataReaderInterface
coercers CoercerInterface
formatters ViolationFormatterInterface

What each extension does: see Extending.

A coercer of a named mapper replaces the one of the default mapper, see Custom Coercers. The same goes for a formatter of a direction, see Formatters.

With barryvdh/laravel-debugbar the bar gets a “mapper” tab: the calls of each mapper with their input, output and violations, the place of the call, the built types and the metadata reads. The calls are also shown on the timeline.

config/type-lang-mapper.php
return [
'profiler' => [
'debugbar' => false, // never
'debugbar' => true, // also with a disabled Debugbar, fails without one
],
];

With Laravel Telescope each call of a mapper is an entry of the “Logs” tab, tied to its request, job or command.

Mapper "api": denormalize(array{id: int}) failed in 0.42 ms
{
"mapper": "api",
"method": "denormalize",
"type": "array{id: int}",
"duration": 0.42,
"error": "TypeLang\\Mapper\\Exception\\InvalidValueException: ...",
"violations": ["$.id: Value must be of type int, but \"x\" given"],
"called at": "/app/Http/Controllers/ApiController.php:42"
}
Entry Level Tags
succeeded call debug type-lang-mapper, type-lang-mapper:api
failed call warning type-lang-mapper, type-lang-mapper:api, type-lang-mapper:failed
config/type-lang-mapper.php
return [
'profiler' => [
'telescope' => false, // never
'telescope' => true, // fails without Telescope
],
];