Download the PHP package cuyz/valinor-bundle without Composer

Symfony integration of Valinor library.

Valinor takes care of the construction and validation of raw inputs (JSON, plain arrays, etc.) into objects, ensuring a perfectly valid state. It allows the objects to be used without having to worry about their integrity during the whole application lifecycle.

The validation system will detect any incorrect value and help the developers by providing precise and human-readable error messages.

The mapper can handle native PHP types as well as other advanced types supported by PHPStan and Psalm like shaped arrays, generics, integer range and more.

The library also provides a normalization mechanism that can help transform any input into a data format (JSON, CSV, …), while preserving the original structure.

Installation

Mapper injection

A mapper instance can be injected in any autowired service in parameters with the type TreeMapper.

It can also be manually injected in a service…

For more granular control, a MapperBuilder instance can be injected instead.

Normalizer injection

A normalizer instance can be injected in any autowired service in parameters with a Normalizer type:

• ArrayNormalizer — injects a normalizer that transforms values to arrays and scalars.
• JsonNormalizer — injects a normalizer that transforms values to JSON.

It can also be manually injected in a service…

For more granular control, a NormalizerBuilder instance can be injected instead.

Bundle configuration

Global configuration for the bundle can be done in a package configuration file…

HTTP Request mapping

The bundle provides automatic mapping of HTTP request values to controller arguments. This feature leverages Valinor's mapping capabilities to handle route parameters, query parameters and request body data.

Lean more about HTTP request mapping in the library documentation.

Note that Symfony provides a similar built-in solution, which makes use of attributes like #[MapQueryString] and #[MapRequestPayload]. This bundle can bring some additional features:

• No need to use attributes unless source enforcement is required.
• Ability to map advanced types like non-empty-string, positive-int, int<10, 100> and more.
• Precise error messages when a request contains invalid values.
• Easy customization of the mapping process using mapper configurators.
• And, in the end, any other feature provided by Valinor's mapping system.

Basic usage

Using the #[MapRequest] on a controller's method enables automatic arguments mapping from route parameters, query parameters and request body data.

It works out of the box, but when it is needed to enforce a specific source for a given parameter, one of the following attributes can be used:

• #[FromRoute] for route parameters
• #[FromQuery] for query parameters
• #[FromBody] for request body values

Example using attributes

Example using attributes

Per-controller mapper configuration

You can customize the mapper behavior for a specific controller by passing mapper configurators to the #[MapRequest] attribute:

APIs often need to define rules concerning the keys cases passed in the request; this can be defined using the following configurators:

• Restricting key case configurators — restricting keys to camelCase, PascalCase, snake_case or kebab-case.
• Converting key case configurators — automatically converting keys to camelCase or snake_case.

Custom request mapping attribute

When multiple controllers share the same mapper configuration (date formats, key case rules, etc.), a custom attribute can be created to avoid repeating the same configurators on every controller.

This is done by implementing the MapRequestAttribute interface directly:

It can then be used in place of #[MapRequest] on any controller method:

Error handling

When mapping fails, the bundle throws an HttpRequestMappingError exception with a 422 Unprocessable Entity status code. The error message includes all validation errors. Example:

Mapping all parameters at once

Instead of mapping individual query parameters or body values to separate parameters, the asRoot option can be used to map all of them at once to a single parameter. This is useful when working with complex data structures or when the number of parameters is large.

The same approach works with #[FromBody(asRoot: true)] for body values.

Request object mapping

When a controller needs to access the original request object, it can be directly added as an argument:

[!NOTE] By enabling the [valinor.http.convert_request_to_psr configuration](

bundle-configuration), controllers can type-hint a PSR-7

ServerRequestInterface parameter instead of Symfony's Request. The bundle will automatically convert the incoming Symfony request to a PSR-7 instance.

This requires the symfony/psr-http-message-bridge package to be installed.

Other features

Customizing mapper builder

Any MapperBuilderConfigurator service tagged with valinor.mapper_builder_configurator.default will be automatically used to customize the default mapper builder.

Customizing normalizer builder

Any NormalizerBuilderConfigurator service tagged with valinor.normalizer_builder_configurator.default will be automatically used to customize the default mapper builder.

Mapping errors in console commands

When running a command using Symfony Console, mapping errors will be caught to enhance the output and give a better idea of what went wrong.

[!NOTE] The maximum number of errors that will be displayed can be configured in the bundle configuration.

Example of output:

Cache warmup

When using Symfony's cache warmup feature — usually bin/console cache:warmup — the mapper cache will be warmed up automatically for all classes that are tagged with the tag valinor.warmup.

This tag can be added manually via service configuration, or automatically for autoconfigured classes using the attribute WarmupForMapper.

[!NOTE] The WarmupForMapper attribute disables dependency injection autowiring for the class it is assigned to. Although autowiring a class that will be instantiated by a mapper makes little sense in most cases, it may still be needed, in which case the $autowire parameter of the attribute can be set to true.

Cache clearing

When using Symfony's cache clearing feature — usually bin/console cache:clear — the cache entries will be cleared automatically for all MapperBuilder and NormalizerBuilder that are tagged respectively with valinor.mapper_builder and valinor.normalizer_builder.