Integrations
Symfony
The bundle registers mappers as services of a Symfony 6.4+ application.
composer require type-lang/mapper-symfonyWith Symfony Flex the bundle is enabled automatically. Otherwise add it to
config/bundles.php:
return [ // ... TypeLang\Mapper\Bridge\Symfony\TypeLangMapperBundle::class => [ 'all' => true, ],];Mappers
Section titled “Mappers”The default mapper is the type_lang_mapper.mapper service, autowired by
MapperInterface, DenormalizerInterface and NormalizerInterface.
use TypeLang\Mapper\DenormalizerInterface;
final class CreateUserController{ public function __construct( private readonly DenormalizerInterface $mapper, ) {}
public function __invoke(Request $request): Response { $user = $this->mapper->denormalize( $request->toArray(), CreateUser::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.mapper.<name> service.
type_lang_mapper: # settings of the default mapper, inherited by the named ones naming: snake_case
mappers: # type_lang_mapper.mapper.api api: # config overrides strict: true
# type_lang_mapper.mapper.import import: # config overrides reject_extra_fields: true max_violations: 100The interfaces are always autowired to the default mapper, whatever the name of the argument. A named mapper is passed by its service id:
services: App\Controller\ImportController: arguments: # snake_case $mapper: '@type_lang_mapper.mapper' # snake_case, strict $apiMapper: '@type_lang_mapper.mapper.api'final class ImportController{ public function __construct( // type_lang_mapper.mapper: snake_case private readonly DenormalizerInterface $mapper, // type_lang_mapper.mapper.api: snake_case, strict private readonly DenormalizerInterface $apiMapper, ) {}}use Symfony\Component\DependencyInjection\Attribute\Autowire;
final class ImportController{ public function __construct( // type_lang_mapper.mapper: snake_case private readonly DenormalizerInterface $mapper, // type_lang_mapper.mapper.api: snake_case, strict #[Autowire(service: 'type_lang_mapper.mapper.api')] private readonly DenormalizerInterface $apiMapper, ) {}}Without the explicit $apiMapper the controller would get the default
mapper there too: the name of an argument never selects a mapper.
Configuration
Section titled “Configuration”type_lang_mapper: # 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: ~
# snake_case, camelCase, PascalCase, SCREAMING_SNAKE_CASE, kebab-case # or a NamingStrategyInterface service naming: ~
# services, see "Extensions" types: [] decorators: [] expanders: [] hooks: [] instantiators: [] accessors: []
# CoercerInterface service by the type coercers: int: ~ float: ~ string: ~ bool: ~ array: ~
# ViolationFormatterInterface service by the direction formatters: denormalization: ~ normalization: ~
metadata: # MetadataReaderInterface services over the default readers readers: []
# config files or directories of them (yaml, yml, neon, json, php) paths: - '%kernel.project_dir%/config/mapping'
# PropertySelectorInterface service selector: ~
cache: # default = false in debug mode, true otherwise enabled: ~ # from the first one checked to the last one, # default = the "cache.type_lang_mapper" pool pools: - { psr16: app.redis, prefix: hot_ } - { psr6: cache.app }
# 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
# default = enabled in debug mode profiler: ~The options are described in Configuration, Naming Strategy, Config Files and Caching.
Extensions
Section titled “Extensions”An extension is a service added to the mappers in one of two ways:
- YAML: its id is listed in the config, at the root for the default
mapper or under
mappers.<name>for a named one; - Attributes: its class carries an attribute of its role and is
autoconfigured, as the classes of
src/are by default.
| Role | Attribute | Config key | What it does |
|---|---|---|---|
| Type builder | AsMapperTypeBuilder |
types |
Custom types |
| Decorator | AsMapperDecorator |
decorators |
Decorators |
| Type expander | AsMapperTypeExpander |
expanders |
Expanders |
| Hook | AsMapperHook |
hooks |
Hooks |
| Instantiator | AsMapperInstantiator |
instantiators |
Instantiators |
| Accessor | AsMapperAccessor |
accessors |
Property accessors |
| Metadata reader | AsMapperMetadataReader |
metadata.readers |
Metadata |
| Coercer | AsMapperCoercer |
coercers.<type> |
Type coercion |
| Formatter | AsMapperFormatter |
formatters.<direction> |
Formatters |
An extension of the default mapper extends the named ones too. An attribute
without mappers extends the default mapper and all named ones,
mappers: ['api'] the api mapper only. Within one role the services of
the config go first, in the order of the config, then the ones of the
attributes by their priority, a higher one first. A named mapper tries its
own services before the ones of the default mapper.
A role with a list of services:
type_lang_mapper: # the default mapper and all named ones types: - App\Mapper\UuidTypeBuilder mappers: api: # the "api" mapper only types: - App\Mapper\MoneyTypeBuilderuse TypeLang\Mapper\Bridge\Symfony\Attribute\AsMapperTypeBuilder;
// the default mapper and all named ones#[AsMapperTypeBuilder]final class UuidTypeBuilder implements TypeBuilderInterface {}
// the "api" mapper only, before the type builders of a lower priority#[AsMapperTypeBuilder(mappers: ['api'], priority: 10)]final class MoneyTypeBuilder implements TypeBuilderInterface {}Decorators, expanders, hooks, instantiators, accessors and metadata readers are added the same way, by their config key and attribute of the table.
Coercers and formatters
Section titled “Coercers and formatters”A mapper has one coercer per type (int, float, string, bool,
array) and one formatter per direction (denormalization,
normalization). The attribute takes the type or the direction instead of
a priority:
type_lang_mapper: coercers: bool: App\Mapper\YesNoCoercer formatters: denormalization: App\Mapper\TranslatedFormatter mappers: api: coercers: float: App\Mapper\DecimalCommaCoerceruse TypeLang\Mapper\Bridge\Symfony\Attribute\AsMapperCoercer;use TypeLang\Mapper\Bridge\Symfony\Attribute\AsMapperFormatter;
#[AsMapperCoercer('bool')]final class YesNoCoercer implements CoercerInterface {}
#[AsMapperFormatter('denormalization')]final class TranslatedFormatter implements ViolationFormatterInterface {}
// the "api" mapper only#[AsMapperCoercer('float', mappers: ['api'])]final class DecimalCommaCoercer implements CoercerInterface {}Profiler
Section titled “Profiler”In debug mode the Symfony profiler gets a “Mapper” panel: the calls of each
mapper with their input, output and violations, the place of the call, the
built types and the metadata reads. With symfony/stopwatch the calls are
also shown on the performance timeline.
type_lang_mapper: profiler: false