Skip to content

Integrations

Symfony

The bundle registers mappers as services of a Symfony 6.4+ application.

composer require type-lang/mapper-symfony

With Symfony Flex the bundle is enabled automatically. Otherwise add it to config/bundles.php:

return [
// ...
TypeLang\Mapper\Bridge\Symfony\TypeLangMapperBundle::class => [
'all' => true,
],
];

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.

config/packages/type_lang_mapper.yaml
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: 100

The interfaces are always autowired to the default mapper, whatever the name of the argument. A named mapper is passed by its service id:

config/services.yaml
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,
) {}
}

Without the explicit $apiMapper the controller would get the default mapper there too: the name of an argument never selects a mapper.

config/packages/type_lang_mapper.yaml
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.

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:

config/packages/type_lang_mapper.yaml
type_lang_mapper:
# the default mapper and all named ones
types:
- App\Mapper\UuidTypeBuilder
mappers:
api:
# the "api" mapper only
types:
- App\Mapper\MoneyTypeBuilder

Decorators, expanders, hooks, instantiators, accessors and metadata readers are added the same way, by their config key and attribute of the table.

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\DecimalCommaCoercer

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