README

Typed request mapping for Mezzio handlers via cuyz/valinor.

This package reads #[MapRequest] attributes on route handlers and maps request input (body/query/route) into DTOs before your handler code runs.

Features

• #[MapRequest] attribute for class and method targets (repeatable)
• Mapping from:
  • parsed body (body)
  • query params (query)
  • route params (route)
  • combined HTTP request (source) using Valinor HTTP attributes (FromBody, FromQuery, FromRoute)
• Optional request attribute key override via output
• HTTP method filter via methods (case-insensitive, normalized to uppercase)
• JSON error responses on mapping failures
• Optional Valinor error message remapping (message_map)

Requirements

• PHP ~8.2 || ~8.3 || ~8.4 || ~8.5
• cuyz/valinor ^2.0
• laminas/laminas-stratigility ^4.3
• mezzio/mezzio ^3.20
• mezzio/mezzio-router ^3.15 || ^4.1
• sirix/mezzio-routing-contracts ^1.0

Installation

composer require sirix/mezzio-valinor-request-mapper

The package auto-registers its config provider via Composer extra config. If your app does not use laminas-config-aggregator, add manually:

\Sirix\Mezzio\Valinor\ConfigProvider::class,

Middleware registration modes

1) Standalone Mezzio (without sirix/mezzio-routing-attributes)

Register middleware globally after route matching and before dispatch:

$app->pipe(\Mezzio\Router\Middleware\RouteMiddleware::class);
$app->pipe(\Sirix\Mezzio\Valinor\Middleware\ValinorRequestMapperMiddleware::class);
$app->pipe(\Mezzio\Router\Middleware\DispatchMiddleware::class);

In standalone mode the middleware resolves #[MapRequest] by reflection from:

• class-level attributes on the matched route handler
• method-level attributes on PSR-15 process()
• method-level attributes on request handler handle() when Mezzio wraps it as route middleware
• method-level attributes on invokable route middleware via __invoke()

2) With sirix/mezzio-routing-attributes

If your app uses sirix/mezzio-routing-attributes and it scans/collects route attribute modifiers, MapRequest is discovered as a RouteAttributeModifierInterface implementation and ValinorRequestMapperMiddleware is attached to matching routes automatically.

In this mode you usually do not need to register \Sirix\Mezzio\Valinor\Middleware\ValinorRequestMapperMiddleware::class as a global pipeline middleware.

Example (class-level + method-level attributes):

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Sirix\Mezzio\Routing\Attributes\Attribute\Get;
use Sirix\Mezzio\Routing\Attributes\Attribute\Post;
use Sirix\Mezzio\Valinor\Attribute\MapRequest;

final readonly class PaginationRequest
{
    public function __construct(public int $page = 1) {}
}

final readonly class CreateOrderRequest
{
    public function __construct(public string $name, public string $email) {}
}

#[MapRequest(query: PaginationRequest::class)]
final class OrdersHandler
{
    #[Get('/orders', name: 'orders.list')]
    public function list(ServerRequestInterface $request): ResponseInterface
    {
        $pagination = $request->getAttribute(PaginationRequest::class);
        // ...
    }

    #[Post('/orders', name: 'orders.create')]
    #[MapRequest(body: CreateOrderRequest::class, output: 'form')]
    public function create(ServerRequestInterface $request): ResponseInterface
    {
        $form = $request->getAttribute('form');
        // ...
    }
}

In this setup #[MapRequest] contributes route middleware via routing attribute processing, so no extra global pipeline registration is required for the mapper middleware.

Quick start

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Sirix\Mezzio\Valinor\Attribute\MapRequest;

final readonly class CreateUserRequest
{
    public function __construct(
        public string $name,
        public string $email,
    ) {}
}

#[MapRequest(body: CreateUserRequest::class)]
final class CreateUserHandler implements RequestHandlerInterface
{
    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        /** @var CreateUserRequest $dto */
        $dto = $request->getAttribute(CreateUserRequest::class);

        // use $dto ...
    }
}

Attribute API

new MapRequest(
    body: ?string,   // class-string DTO from parsed body
    query: ?string,  // class-string DTO from query params
    route: ?string,  // class-string DTO from route params
    source: ?string, // class-string DTO from combined request sources
    output: ?string, // request attribute key, defaults to DTO FQCN
    methods: array,  // HTTP methods filter
);

Rules:

• source is mutually exclusive with body/query/route
• if output is omitted, mapped DTO is stored under its class name
• methods = [] means any HTTP method
• methods are normalized (post, Post -> POST)
• if multiple #[MapRequest] attributes match current method, all of them are applied in declaration order; class-level mappings run before method-level mappings

Combined mapping (source)

Use Valinor HTTP source attributes in DTO constructor:

use CuyZ\Valinor\Mapper\Http\FromBody;
use CuyZ\Valinor\Mapper\Http\FromQuery;
use CuyZ\Valinor\Mapper\Http\FromRoute;

final readonly class SearchRequest
{
    public function __construct(
        #[FromRoute] public string $locale,
        #[FromQuery] public string $q,
        #[FromBody] public ?array $filters = null,
    ) {}
}

#[MapRequest(source: SearchRequest::class)]
final class SearchHandler implements RequestHandlerInterface
{
    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        $dto = $request->getAttribute(SearchRequest::class);
        // ...
    }
}

Configuration

Create config/autoload/mezzio-valinor.global.php:

<?php

declare(strict_types=1);

return [
    'sirix_mezzio_valinor' => [
        'mapper' => [
            'cache_dir' => __DIR__ . '/../../cache/valinor',
            'cache_watch' => false,
            'configurators' => [
                \CuyZ\Valinor\Mapper\Configurator\ConvertKeysToCamelCase::class,
            ],
            'allow_superfluous_keys' => true,
            'allow_scalar_value_casting' => true,
            'allow_permissive_types' => false,
            'allow_undefined_values' => false,
            'support_date_formats' => ['Y-m-d', 'd/m/Y'],
        ],
        'error' => [
            'status_code' => 422,
            'key_case' => null, // null|'snake_case'
            'message_map' => [
                // 'Value {source_value} is not a valid string.' => 'This field is required.',
            ],
        ],
    ],
];

Mapper options

Cache

When cache_dir is set, Valinor caches compiled reflection data for mapped DTO types, significantly reducing first-request latency.

• Production: set cache_dir and leave cache_watch disabled (default)
• Development: set cache_watch: true so cache invalidates automatically when PHP files change

To pre-warm the cache during deployment, use a CLI script:

$mapperBuilder = (new \CuyZ\Valinor\MapperBuilder())
    ->withCache(new \CuyZ\Valinor\Cache\FileSystemCache('path/to/cache-dir'));

$mapperBuilder->warmupCacheFor(
    \App\Domain\CreateUserRequest::class,
    \App\Domain\PaginationRequest::class,
    // ...
);

Mapper configurators

mapper.configurators supports:

• service id (resolved from container)
• class-string implementing MapperBuilderConfigurator (instantiated if service not found)

Error options

Error response format

On mapping failure middleware returns JSON:

{
  "error": "Mapping failed",
  "messages": {
    "field": ["...message..."]
  }
}

Status code defaults to 422 and can be overridden by sirix_mezzio_valinor.error.status_code.

Notes and caveats

• Middleware requires RouteResult attribute (it is a no-op when route is not matched yet).
• With sirix/mezzio-routing-attributes, middleware can be added per-route automatically via attribute scanning.
• For body mapping, malformed body structures can still fail at Valinor level and return configured mapping error response.
• When using a custom output, ensure downstream code reads the same request key.

Release checklist

Before tagging a stable release:

composer validate --strict
composer normalize --dry-run --diff
composer analyse-deps
composer check