Update dependency cuyz/valinor-bundle to ^2.3.0

[renovate]

This PR contains the following updates:

Package	Change	Age	Adoption	Passing	Confidence
cuyz/valinor-bundle	^2.2.0 → ^2.3.0

---

Release Notes

CuyZ/Valinor-Bundle (cuyz/valinor-bundle)

v2.3.0

Compare Source

Notable changes

HTTP request mapping support

The bundle provides automatic mapping of HTTP request values to controller
arguments using attributes. This feature leverages Valinor's mapping
capabilities to handle route parameters, query values, 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:

• 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
mapping.

Arguments can be mapped from different sources:

• Route parameters — using #[FromRoute] attribute
• Query parameters — using #[FromQuery] attribute
• Request body — using #[FromBody] attribute

Basic example:

use CuyZ\Valinor\Mapper\Http\FromQuery;
use CuyZ\Valinor\Mapper\Http\FromRoute;
use CuyZ\ValinorBundle\Http\MapRequest;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Attribute\Route;

#[AsController]
final class ListArticles
{
    /**
     * GET /api/authors/{authorId}/articles?status=X&page=X&limit=X
     *
     * @​param positive-int $page
     * @&#8203;param int<10, 100> $limit
     */
    #[Route('/api/authors/{authorId}/articles', methods: 'GET')]
    #[MapRequest]
    public function __invoke(
        // Comes from the route
        #[FromRoute] string $authorId,

        // All come from query parameters
        #[FromQuery] string $status,
        #[FromQuery] int $page = 1,
        #[FromQuery] int $limit = 10,
    ): Response { /* … */ }
}

Per-controller mapper configuration

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

use CuyZ\Valinor\Mapper\Configurator\ConvertKeysToCamelCase;
use CuyZ\Valinor\Mapper\Http\FromBody;
use CuyZ\ValinorBundle\Http\MapRequest;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Attribute\Route;

#[AsController]
final class CreateAuthor
{
    #[Route('/api/authors/new', methods: 'POST')]
    #[MapRequest(new ConvertKeysToCamelCase())]
    public function __invoke(
        #[FromBody] string $name,
        #[FromBody] DateTimeInterface $birthDate,
    ): Response { /* … */ }
}

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:

use Attribute;
use CuyZ\Valinor\Mapper\Configurator\ConvertKeysToCamelCase;
use CuyZ\Valinor\Mapper\Configurator\RestrictKeysToSnakeCase;
use CuyZ\Valinor\MapperBuilder;
use CuyZ\ValinorBundle\Http\MapRequestAttribute;

#[Attribute(Attribute::TARGET_METHOD)]
final class MyAppMapRequest implements MapRequestAttribute
{
    public function __construct(
        /** @&#8203;var list<non-empty-string> */
        private array $dateFormats = ['Y-m-d', 'Y-m-d H:i:s'],
        private bool $allowSuperfluousKeys = false,
    ) {}

    public function configureMapperBuilder(MapperBuilder $builder): MapperBuilder
    {
        $builder = $builder->configureWith(
            // Always restrict keys to `snake_case`
            new RestrictKeysToSnakeCase(),
            // Always convert keys to `camelCase`
            new ConvertKeysToCamelCase(),
        );

        $builder = $builder->supportDateFormats(...$this->dateFormats);

        if ($this->allowSuperfluousKeys) {
            $builder = $builder->allowSuperfluousKeys();
        }

        return $builder;
    }
}

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

use CuyZ\Valinor\Mapper\Http\FromBody;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Attribute\Route;

#[AsController]
final class CreateComment
{
    #[Route('/api/comments', methods: 'POST')]
    #[MyAppMapRequest(
        dateFormats: ['d/m/Y'],
        allowSuperfluousKeys: true,
    )]
    public function __invoke(
        #[FromBody] string $author,
        #[FromBody] string $content,
    ): Response { /* … */ }
}

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:

HTTP request is invalid, a total of 2 error(s) were found:
- page: value 0 is not a valid positive integer.
- limit: value 150 is not a valid integer between 10 and 100.

Mapping all parameters at once

Instead of mapping individual query parameters or body values to
separate parameters, the mapAll 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.

use CuyZ\Valinor\Mapper\Http\FromQuery;
use CuyZ\Valinor\Mapper\Http\FromRoute;
use CuyZ\ValinorBundle\Http\MapRequest;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Attribute\Route;

final readonly class ArticleFilters
{
    public function __construct(
        public string $status,
        /** @​var positive-int */
        public int $page = 1,
        /** @&#8203;var int<10, 100> */
        public int $limit = 10,
    ) {}
}

#[AsController]
final class ListArticles
{
    /**
     * GET /api/authors/{authorId}/articles?status=X&page=X&limit=X
     */
    #[Route('/api/authors/{authorId}/articles', methods: 'GET')]
    #[MapRequest]
    public function __invoke(
        #[FromRoute] string $authorId,
        #[FromQuery(mapAll: true)] ArticleFilters $filters,
    ): Response { /* … */ }
}

The same approach works with #[FromBody(mapAll: 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:

use CuyZ\Valinor\Mapper\Http\FromRoute;
use CuyZ\ValinorBundle\Http\MapRequest;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Attribute\Route;

#[AsController]
final class ListArticles
{
    #[Route('/api/authors/{authorId}/articles', methods: 'GET')]
    #[MapRequest]
    public function __invoke(
        // Request object injected automatically
        Request $request,

        #[FromRoute] string $authorId,
    ): Response {
        if ($request->headers->has('My-Customer-Header')) {
            // …
        }
    }
}

Note — by enabling the valinor.http.convert_request_to_psr
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.

Features

• Add support for HTTP request mapping using attributes (3b4c6b)
• Support upstream library configurator interfaces (af68ac)

---

---

Configuration

📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

---

• If you want to rebase/retry this PR, check this box

---

This PR was generated by Mend Renovate. View the repository job log.