Integrations
Laravel
The service provider registers mappers in the container of a Laravel 10+ application. It is discovered automatically.
composer require type-lang/mapper-laravelphp artisan vendor:publish --tag=type-lang-mapper-configMappers
Section titled “Mappers”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.
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');Configuration
Section titled “Configuration”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.
Extensions
Section titled “Extensions”An extension is a class name or a container id, resolved with the container.
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.
Debugbar
Section titled “Debugbar”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.
return [ 'profiler' => [ 'debugbar' => false, // never 'debugbar' => true, // also with a disabled Debugbar, fails without one ],];Telescope
Section titled “Telescope”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 |
return [ 'profiler' => [ 'telescope' => false, // never 'telescope' => true, // fails without Telescope ],];