Mapping HTTP request parameters using Valinor for type-safe controller calls

[romm]

I've lately been working on native HTTP request mapping, provided out of the box by this library. The goal is to ease the validation and mapping of the HTTP request's parts — query parameters, (route) parameters and body — to ensure everything is typed properly before being used inside the controller.

This system would be used in a HTTP application, somewhere between the route resolving and the controller call.

---

I've got a POC working well, and now I'm reflecting on the best way of structuring the different HTTP parts in the controller parameters, I'd love to have some input about the possible options.

Let's imagine the following HTTP request (it does not particularly makes sense, just to have an idea of what could be done):

// PATCH https://example.com/user/78cbc7bf?optionA=foo&optionB=bar
// Content-Type: application/json
// {"name": "John Doe", "email": "john.doe@example.com"}
//
// $request is built somewhere in the application by the router:
$request = HttpRequest::new(
    attributes: [
        'userId' => '78cbc7bf',
    ],
    query: [
        'optionA' => 'foo',
        'optionB' => 'bar',
    ],
    body: [
        'name' => 'John Doe',
        'email' => 'john.doe@example.com',
    ],
);

The goal is to be able to map this request to either a DTO or a controller's arguments signature:

(new MapperBuilder())
    ->mapper()
    ->map(MyDTO::class, $request);

// or…

(new MapperBuilder())
    ->argumentsMapper()
    ->mapArguments($myController, $request);

Now I'm considering several options on how to define the structure where the data should be mapped:

Option A

ℹ️ See this option live in Pull Request #748

1. Route parameters are mapped at the root level
2. Query parameters are mapped on a parameter flagged with a #[MapQuery] attribute — the parameter can be either an array shape or a DTO
3. Request body is mapped on a parameter flagged with a #[MapBody] attribute — the parameter can be either an array shape or a DTO

Pros: clear distinction between the three sources of data
Cons: an attribute must be used; an array shape (or a DTO) must be used even for simple cases

Show code example ⤵️

// Map request to a DTO:
final readonly class MyDTO
{
    
    public function __construct(
        public string $userId,

        /** @var array{optionA: string, optionB: string} */
        #[MapQuery] public array $query,
        // or…
        #[MapQuery] public SomeQueryDTO $query,

        /** @var array{name: string, email: string} */
        #[MapBody] public array $payload,
        // or…
        #[MapBody] public SomeBodyDTO $payload,
    ) {}
}

// Map request to a controller action:
final class MyController
{
    #[Route('PATCH', 'user/{userId}')]
    public function __invoke(
        string $userId,

        /** @var array{optionA: string, optionB: string} */
        #[MapQuery] array $query,
        // or…
        #[MapQuery] SomeQueryDTO $query,

        /** @var array{name: string, email: string} */
        #[MapBody] array $payload,
        // or…
        #[MapBody] SomeBodyDTO $payload,
        
    ): ResponseInterface {
        // …
    }
}

---

Option B

1. Route parameters are mapped at the root level
2. Query parameters are mapped at the root level
3. Request body is mapped on a parameter flagged with a #[MapBody] attribute — the parameter can be either an array shape or a DTO

Pros: it gets easier to map query string as we don't need an array shape or a DTO
Cons: inconsistency on the way of declaring the parameters; collision between route attributes and query parameters can happen

Show code example ⤵️

// Map request to a DTO:
final readonly class MyDTO
{

    public function __construct(
        public string $userId,  // Comes from the route
        public string $optionA, // Comes from query parameter
        public string $optionB, // Comes from query parameter

        /** @var array{name: string, email: string} */
        #[MapBody] public array $payload,
        // or…
        #[MapBody] public SomeBodyDTO $payload,
    ) {}
}

// Map request to a controller action:
final class MyController
{
    #[Route('PATCH', 'user/{userId}')]
    public function __invoke(
        string $userId,  // Comes from the route
        string $optionA, // Comes from query parameter
        string $optionB, // Comes from query parameter

        /** @var array{name: string, email: string} */
        #[MapBody] array $payload,
        // or…
        #[MapBody] SomeBodyDTO $payload,

    ): ResponseInterface {
        // …
    }
}

---

Option C

1. Route parameters are mapped at the root level
2. Query parameters are mapped at the root level
3. Request body is mapped at the root level

Pros: consistency; easy to declare any parameter; no need for attribute
Cons: collision between route attributes, query parameters or body can happen; signature can get heavy quite fast when a lot of information is passed

Show code example ⤵️

// Map request to a DTO:
final readonly class MyDTO
{

    public function __construct(
        public string $userId,  // Comes from the route
        public string $optionA, // Comes from query parameter
        public string $optionB, // Comes from query parameter
        public string $name,    // Comes from body payload
        public string $email,   // Comes from body payload
    ) {}
}

// Map request to a controller action:
final class MyController
{
    #[Route('PATCH', 'user/{userId}')]
    public function __invoke(
        string $userId,  // Comes from the route
        string $optionA, // Comes from query parameter
        string $optionB, // Comes from query parameter
        string $name,    // Comes from body payload
        string $email,   // Comes from body payload
    ): ResponseInterface {
        // …
    }
}

---

Option D

1. Route parameters are mapped at the root level
2. IF a #[MapQuery] attribute is found on a parameter, all query parameters are mapped on it, otherwise they are mapped at the root level
3. IF a #[MapBody] attribute is found on a parameter, all body values are mapped on it, otherwise they are mapped at the root level

Pros: very flexible; allows to choose which option is the best for a given situation
Cons: can lead to inconsistency between different controllers

---

Option E

ℹ️ See this option live in Pull Request #747

This option aims to bypass the two main issues with other options above:

1. Collisions between query parameters and body values
2. Usage of attribute

The idea is that in most cases, safe methods like GET, HEAD & others rely on query parameters only, whereas POST, PUT & others rely on body values only/mostly. If we acknowledge that, we can simplify things in almost all cases.

To do this, everything is mapped at the root level, but:

• If the method is safe (GET, HEAD, …) only the query parameters are mapped
• If the method is not safe (POST, PUT, …) only the body values are mapped

Route parameters are always mapped.

When there's a case where a request POST / PUT / other, needs to access query parameters, we can always give access to the original request object to access them (we need to define more precisely how to do it).

Pros: no risk of collision, no usage of attributes
Cons: if a controller needs to access further data, it must use the request object (see below)

Show code example ⤵️

// When routing to a GET method:
final class MyController
{
    #[Route('GET', 'user/{userId}')]
    public function __invoke(
        string $userId,  // Comes from the route
        string $optionA, // Comes from query parameter
        string $optionB, // Comes from query parameter
    ): ResponseInterface
    {
        // …
    }
}

// When routing to a POST method:
final class MyController
{
    #[Route('POST', 'user/{userId}')]
    public function __invoke(
        string $userId,  // Comes from the route
        string $name,    // Comes from body payload
        string $email,   // Comes from body payload
    ): ResponseInterface
    {
        // …
    }
}

// If we need to use query parameters in a POST method:
final class MyController
{
    #[Route('POST', 'user/{userId}')]
    public function __invoke(
        string $userId,  // Comes from the route
        string $name,    // Comes from body payload
        string $email,   // Comes from body payload

        // Could be the original request object (for instance PSR's ServerRequestInterface), to be defined
        RequestObject $request,
    ): ResponseInterface
    {
        $optionA = $request->getQueryParams()['optionA'];
        $optionB = $request->getQueryParams()['optionB'];
        
        // …
    }
}

---

On a side note, Symfony has a similar built-in feature:

• Route parameters are directly mapped to name-matching parameters
• Query parameters can be either mapped to all parameters that use the #[MapQueryParameter] attribute, or flattened to a single parameter using the #[MapQueryString] attribute
• Request body can be mapped to a DTO using the #[MapRequestPayload] attribute

---

Updated on 20th October 2025: added option E which resets the poll so here are the results at this time:

Show poll results

[shulard]

That’s an interesting behavior! Will you rely on PSRs to describe a “Request”?

[romm]

That’s an interesting behavior! Will you rely on PSRs to describe a “Request”?

We wont rely on it so that any app/framework can use it, although we will probably give access to something like HttpRequest::fromPsr(ServerRequestInterface $request): HttpRequest or similar. 😊

[dtdesign]

We have been doing something similar lately using DTOs defined alongside the controller but we are using a helper class that performs the mapping any error handling. This has the advantage that we are able to implement them as PSR-7 controllers on the other hand it requires boiler-plate code in every controller.

That said, I’m not entirely convinced that boiler-plate code is always a bad thing, after all this trade-off allows us to stick to PSR-7 while also being able to enforce the call signature of the controller on an interface level. The drawback of parameter arguments is that interfaces are pretty much out of the window immediately.

For reference, we currently have two iterations of this principle in action:

1. Manual mapping inside a PSR-7 controller from our first iteration that can map query parameters as well as the request body.
2. Simplified mapping that uses a DTO inside a custom controller implementation that relies on the HTTP verb to resolve where to take the data from

The second iteration is much closer to this proposal and is meant to illustrate how these things could look in practice. During the implementation we tried out your approach of using attributes on arguments but the lack of interface support was a major let down.

I do have to add that there is one thing lurking in the shadows and it’s the array $variables argument of __invoke(). The second iteration is based around v2.0.0-beta1 of nikic/FastRoute that we are using to register and map controllers. For example, #[DeleteRequest('/core/comments/{id:\d+}')] would only match a route with a mandatory
id that is then provided as 'id' in the one-dimensional array $variables as an integer (drawback: no IDE support). It’s certainly not a perfect approach but this way we can use interfaces for the controllers …

In the end I’m a bit torn between your proposals because none of them really tick all the boxes. Do you think you can come up with an approach that is built on top of PSR-7 to increase compatibility with existing routing implementations?

[romm]

Hi @dtdesign thanks for the detailed answer, helps a lot to understand how it is used in real use-cases. 😊

From what I see, this would look very much like you second iteration indeed, so I'm glad this would fit.

I do have to add that there is one thing lurking in the shadows and it’s the array $variables argument of __invoke(). The second iteration is based around v2.0.0-beta1 of nikic/FastRoute that we are using to register and map controllers. For example, #[DeleteRequest('/core/comments/{id:\d+}')] would only match a route with a mandatory
id that is then provided as 'id' in the one-dimensional array $variables as an integer (drawback: no IDE support). It’s certainly not a perfect approach but this way we can use interfaces for the controllers …

You're actually talking about what I called "route parameters" in the main thread, and the difference with how you handle that is that they are directly part of the request, see this example borrowed from the example above:

// PATCH https://example.com/user/78cbc7bf?optionA=foo&optionB=bar
// Content-Type: application/json
// {"name": "John Doe", "email": "john.doe@example.com"}
//
// $request is built somewhere in the application by the router:
$request = HttpRequest::new(
    attributes: [
        'userId' => '78cbc7bf',
    ],
    query: [
        'optionA' => 'foo',
        'optionB' => 'bar',
    ],
    body: [
        'name' => 'John Doe',
        'email' => 'john.doe@example.com',
    ],
);

So to make it work properly, you should have a way to "inject" the route parameters in the request object, usually this would be done using the ServerRequestInterface::withAttribute() method. For instance, that's how Mezzio's router hands over this information.

So in your case, you would hook into FastRoute to add a request attribute containing the route parameters, and then you can get them back from your PSR-15 controller and give everything to Valinor's mapper.

What do you think?

[dtdesign]

Thank you for pointing out that we could have used request attributes instead of relying on the $variables array. We’re handling the whole mapping to the attribute ourselves so that has always been an option. Shows once again that just because you know something that mean you actually think of it …

I thought about this throughout the day and I will split it off into a separate answer because it doesn’t relate that much to my initial answer, which was meant to provide you with some real-life examples and not necessarily a recommendation.

[dtdesign]

Thinking about your approach, I see a few difficulties in practice. You’ve set yourself the goal to provide a flexible solution that fits a wide range of use cases but at the same time you cannot make assumptions about how the data gets there. At the same time, offering any sort of support for PSR-7 controllers (which are not that exotic) is somewhat reasonable but means that you have to maintain two (similar) code paths for the same feature.

Having attributes like #[MapBody] or #[MapQuery] only works by accessing superglobals. That rules out approaches where requests are handled in an event loop but I am sure this is something you are well aware of. The other problem is that this prevents any sort of normalization/transformation/filtering going on unless that process is applied by writing to the superglobals.

It also has the problem that these attributes can be misused since they rely on a mutable global state. Calling them in multiple places within the same request can possibly yield different results. I’m not sure if this is even a thing and if you should even consider this in the first place, but it struck my mind more than once. At least with third party libraries there is always a risk that they mutate superglobals in an unpredictable way.

Have you considered introducing a component that needs to be initialized and that offers convenient methods to fetch (and implicitly validate) the values? Something like Foo::fromSuperGlobals() or Foo::fromPsr7($request) that serves as the entry point and returns and object that exposes helper methods like $parameters = $foo->mapQuery(MyFancyDto::class) or $values = $foo->mapBody(FancyBodyDto::class). Some extra methods to support array shapes could come in handy if you cannot meaningfully combine them into one without having type parsers burst into flames. The initialization could take place at the routing level and passed in as the parameter to things like __invoke() or as an attribute (PSR-7).

That approach would be a lot less fancy but offers multiple entry points for the parameters with everything that follows after being completely uniform. The state is encapsulated and immutable, avoiding a whole class of headaches, you don’t have to maintain multiple code paths and you don’t have to deal with any routing (or make any assumptions in that direction).

Perhaps I am overthinking this …

[romm]

I think there has been a misunderstanding, the goal has never been of relying on superglobals. Instead, a class like HttpRequest would be provided by the library, which is a basic DTO containing request information — as stated in this comment we would probably provide a named constructor for PSR request objects out of the box. But the data can come from any library/framework/app.

I like the idea of a "request mapper" though, giving access to mapQuery / mapBody methods. I will probably give it a try and see how it can go, this could actually become the final API, thanks for the idea. 😊

[chapa]

This sounds very promising!

I have been following your work on this library for some time now (from afar), thinking that one day I would use it to replace Symfony's Serializer component, which is a little painful to work with when it comes to deserializing into strongly typed data structures.

I like the option A because of the explicitness it provides: you have to tag an attribute if you want the data coming from the query parameters or request body.
I like options C because having everything mapped at the root level would make DTO objects more "application-oriented" (application logic drives the design of the object) and less "technically constrained" (the fact that it comes from an http request drives the design). But I think it (as well as option B) could be dangerous if we can't control where the data comes from (e.g. $userId is expected to come from the route, but can be overriden with a query parameter or in the request body).

Maybe we can consider adding some attributes to option A, something like #[MapFromQuery] and #[MapFromBody] that would behave like option C (extract the data from the query or the body).
This way:

• all attributes are comming from the route by default,
• query parameters (all at once) and request body can be mapped to single attributes with (respectively) #[MapQuery] and #[MapBody],
• each query parameter and each attribute of the request body can be mapped to attributes with #[MapFromQuery] and #[MapFromBody].

Show code example ⤵️

// Map request to a DTO:
final readonly class MyDTO
{
    public function __construct(
        public string $userId,

        // Query parameters
        #[MapFromQuery] public string $optionA,
        #[MapFromQuery] public string $optionB,

        // Request body attributes
        #[MapFromBody] public string $name,
        #[MapFromBody] public string $email,
    ) {}
}

// Map request to a controller action:
final class MyController
{
    #[Route('PATCH', 'user/{userId}')]
    public function __invoke(
        string $userId,

        // Query parameters
        #[MapFromQuery] string $optionA,
        #[MapFromQuery] string $optionB,

        // Request body attributes
        #[MapFromBody] string $name,
        #[MapFromBody] string $email,
    ): ResponseInterface {
        // …
    }
}

There still is an inconvenient with this approach: it's a little painful when you want to map every fields from the query or from the request because you have to add attributes everywhere. This could be addressed with more attributes (yeah!) to place at the "container" level, something like #[MapAllFromQuery] and #[MapAllFromBody] (or reuse #[MapQuery] and #[MapBody], which could make sens since #[MapSomething] means "put all the something here").

But then, if we have attributes at container level, it could be useful to also have a #[MapFromRoute] (even #[MapRoute]?) for when we still have some route parameters to map even if all the others come from the query or request body.

Show code example ⤵️

// Map request to a DTO:
#[MapBody]
final readonly class MyDTO
{
    public function __construct(
    	#[MapFromRoute] public string $userId,

        // Query parameters
        #[MapFromQuery] public string $optionA,
        #[MapFromQuery] public string $optionB,

        // Request body attributes (in much greater numbers)
        public string $name,
        public string $email,
    ) {}
}

// Map request to a controller action:
final class MyController
{
    #[Route('PATCH', 'user/{userId}'), MapBody]
    public function __invoke(
        #[MapFromRoute] string $userId,

        // Query parameters
        #[MapFromQuery] string $optionA,
        #[MapFromQuery] string $optionB,

        // Request body attributes (in much greater numbers)
        string $name,
        string $email,
    ): ResponseInterface {
        // …
    }
}

// A more realistic example for a controller:
final class MyController
{
    #[Route('PATCH', 'user/{userId}')]
    public function __invoke(
        string $userId,

        // Query parameters
        #[MapFromQuery] string $optionA,
        #[MapFromQuery] string $optionB,

        /** @var array{name: string, email: string} */
        #[MapBody] array $payload,
        // or…
        #[MapBody] SomeBodyDTO $payload,
    ): ResponseInterface {
        // …
    }
}

[romm]

Thank you for your feedback 🙏

That's interesting to see how you'd have imagined it, I'll keep your ideas in mind.

In the meantime, I'd really love to have feedback on my new comment: #736 (comment) — would you mind checking it out? 🤗

[romm]

Thank you all for your answers!

There's also another option I had in mind ~2 months ago and I kind of forgot about it, so I added option E to the thread, would you mind checking it out?

I'd really love to have feedback on your own usage of query parameters. Do you use them exclusively for GET / HEAD / etc. methods? Do you also use them for POST / PUT / etc. methods? Often? If yes, are there many query parameters?

[chapa]

I suppose it's a matter of taste, but I don't really like this new option E.

The HTTP spec doesn't state that safe methods mostly rely on query parameters, nor that non safe methods mostly rely on body values.
So it's a party that the library wants to chose, and although I'm not against by principle, here I think there is too much magic :

• it's an arbitrary rule to learn,
• it adds cognitive load because of the implicitness,
• mistake is easy (change a method and the whole data is taken from elsewhere).

Moreover, there are still potential collisions between route parameters and query/body, so the initial problem it tries to address is not fully addressed (but it still brings what I listed above).

Also, will the mapping of query parameters in non safe methods or body in safe methods¹ still be possible in a DTO ? Not sure how with your examples.

¹: although it may seem strange, GET requests can have bodies

[dtdesign]

We allow query parameters only for GET and DELETE requests, although technically with the exception of parameters that are embedded in the route like an identifier or an id.

For all other methods we put everything into the body. Although you may want to make sure that the body is only parsed if any data is requested from it through the method signature.

An example for this exception is our route that is used to upload files. upload_max_filesize is more often than not kept at the laughable default of 2 MB, therefore we dump binary data into the body and process it as such on the server by reading the raw body.

Regarding @chapa's objections, I do agree that any sort of implicit behavior is at least debatable and I’m generally not a fan of it either. You’re effectively trading “save a couple keystrokes” for a lot of hidden behavior. You could make this much more transparent by slapping an attribute onto each parameter but then you end up with the issue that is requires shared data between the route and the parameter.

At this point you can just use an explicit helper method to map an request object to a DTO which accomplishes the same but does not require any code inspection to understand what is happening. I believe that you do run into the danger of effectively building two thirds of a router implementation here?

And please do not get me wrong: You’ve done an amazing work so far and continue to impress with meaningful and useful improvements. I just know from way too many years of experience how easy it is to get carried away.

[romm]

Thank you for your detailed answers.

I agree with you that option E may seem more opinionated than option A — although I'd say that no matter what solution we go for, at the end this will be opinionated anyway. We will never be able to cover all cases, the goal here is to understand what people do in modern API development, and how they use HTTP to do that, so that we can cover 95% of the overall cases to help them handling strong types in this area.

At this point there are mainly two key points: feasibility and preferences. I've been working on a POC for option E (I will soon push it so you can check it out), although this may not be the preferred way for some of you, this is by far the more feasible/maintainable option which could be more important than personal preferences (no offense, of course 😊). And I'm glad discussions about this topic could lead to where we are now!

---

Answering @chapa:

The HTTP spec doesn't state that safe methods mostly rely on query parameters, nor that non safe methods mostly rely on body values. So it's a party that the library wants to chose, and although I'm not against by principle, here I think there is too much magic :

* it's an arbitrary rule to learn,

* it adds cognitive load because of the implicitness,

I agree partially, because the other options that use attributes also need learning. It is more implicit, but mapping values to a controller/DTO from a request is quite straightforward: in most cases query parameters come only from a GET / … request and body payload comes from a POST / … request — if we agree on that it becomes very logical (IMHO) to have implicit mapping of those values. But, again, it's a biased opinion.

* mistake is easy (change a method and the whole data is taken from elsewhere).

Let's be honest, when was the last time you changed a route from GET to POST? 😁

Moreover, there are still potential collisions between route parameters and query/body, so the initial problem it tries to address is not fully addressed (but it still brings what I listed above).

Actually not really: route parameters names come from the configuration/codebase, as well as the accepted signature of a request's query/body. If there is a collision (which probably wont happen in 99% cases), you could just rename a route parameter which is invisible for the end user anyway.

This issue is far more complicated to handle when working with both query parameters and body payload.

Also, will the mapping of query parameters in non safe methods or body in safe methods¹ still be possible in a DTO ? Not sure how with your examples.

It will, just differently. From what I can see now, the best way would be to have the original request object be part of the signature, so that you can access whatever data you need, and map them the way you desire. Again: 95% cases covered with the provided solution, and for edge-cases you still can do whatever you want from your request.

---

Answering @dtdesign:

An example for this exception is our route that is used to upload files. upload_max_filesize is more often than not kept at the laughable default of 2 MB, therefore we dump binary data into the body and process it as such on the server by reading the raw body.

This clearly looks like an abuse, so for me we should not address this kind of cases 😅 — although uploaded files support should be an option at some point (probably later).

You’re effectively trading “save a couple keystrokes” for a lot of hidden behavior.

Saving a couple of keystrokes, but also improving readability 😊 — also, this is not a lot of hidden behavior, the resulting implementation is easier to understand and to maintain (see above).

You could make this much more transparent by slapping an attribute onto each parameter but then you end up with the issue that is requires shared data between the route and the parameter.

I answered in this reply already. 😊

At this point you can just use an explicit helper method to map an request object to a DTO which accomplishes the same but does not require any code inspection to understand what is happening. I believe that you do run into the danger of effectively building two thirds of a router implementation here?

Absolutely not: the router work was done already at this point, we just need to access its values. There is nothing more happening than mapping of a request's values to a desired structure. Routing is another thing completely separated from this.

And please do not get me wrong: You’ve done an amazing work so far and continue to impress with meaningful and useful improvements. I just know from way too many years of experience how easy it is to get carried away.

Thank you for the kind words, let's keep up the work together. My proposal now is: I get a POC ready, as well as implementation examples, then we see where we go. Deal? 😎

---

Again, thank you for your very valuable feedback. 🙏

[Baptouuuu]

The new E option seems the most practical.

As a reference at work out of 171 endpoints in a single app we only have one that use query parameters. It's a POST endpoint used as a callback url for OnlyOffice to send files. The parameter is used to contain a JWT that is read by the security layer, the controller is not aware of it.

As for the GET endpoints we always express parameters as route parameters.

So even only mapping body parameters would be enough in our case.

[nyamsprod]

This comment might be a bit off topic but looking at your example I will have to comment the query parameters bit. Since this is not yet set in stone I believe this is the one chance to handle thing differently in PHP land which would be beneficial for everyone 🤞🏾.

In your example you have done this:

     query: [
        'optionA' => 'foo',
        'optionB' => 'bar',
    ],

I presume that at some point you did use parse_str. I and will also presume that when building the response developers will use http_build_query. I know that historically query parameters are always mapped to associative arrays in PHP world BUT from my experience and looking at other languages query representation I am convinced that PHP is doing it the wrong way.

If you look for instance at the only valid RFC around query parameters ie the URL Living Standard you will see that query parameters are stored as query pairs. which means that your example would instead yield the following :

    query: [
     ['optionA', 'foo'],
     ['optionB', 'bar'],
   ],

While this may seem weird or original at first glance, there are several advantages in parsing the query string (or POST body) this way:

• PHP handling of parameters as associative array disallow repeating query parameters, the last parameter name encountered override all the other values and is the value that lands in your DTO. While most of the time this is fine you still have lost information during parsing. The original query is not preserved!!

• Every developer has stumble at least once on the parse_str + http_build_query roundtrip issue. Parsing and building the query does not restore the original input. This might be crucial if you are doing some URL signing or if the order or your query/post body parameters are important.

In contrary:

The "new" storage format DO guarantee that:

• the original input is preserved in position and in values;
• you can ALWAYS reconstruct the PHP's associative way from the pair;
• your roundtrip is also preserve (given that you stop using http_build_query and parse_str);

Which means that it makes your Request more interoperable with other language and improve developer DX in cases where position and value are important.

Again sorry for the slightly of topic critics but I believe that if Valinor wants to enter the realm of Request -> DTO handling it should also try to add new/innovative ways to handle the request and I believe this is an important topic to raise at this point otherwise the ship will have sail. I hope you will at least consider the proposition.

[romm]

Hi @nyamsprod, thank you for the answer.

I believe I understand the issue here, however it seems this is completely out of the scope of this topic. The mapping occurs way after the request has been parsed, and it is not intended to introduce this kind of processing inside the library (this is too far from the original goal of the library).

However we could add recommendations in the documentation on what should happen before the request's values are being mapped.

Just to understand more clearly, could you give examples of URL => query parameters parsing results, using the way you described?

[nyamsprod]

@romm I will use the Query class from league/uri-components

use League\Uri\Components\Query;

$query_string = 'foo[]=bar&foo[]=baz&foo=1&foo=2';

$query = Query::new($query_string);
$query->get('foo[]');               // returns 'bar'
$query->getAll('foo[]');            // returns ['bar', 'baz']
$query->get('foo');                 // returns ['1']
$query->getAll('foo');              // returns ['1', '2']
$query->parameter('foo');           // returns '2'
echo $query;                        // returns 'foo[]=bar&foo[]=baz&foo=1&foo=2'

//the round trip issue
parse_str($query_string, $parameters);
$parameters;                   // returns ['foo' => '2']
http_build_query($parameters); // returns 'foo=2' 

The Query class uses the algorithm of the the URL Living Standard - UrlSearchParams class for the get() and getAll methods.

You can easily reproduce these results in your browser as all modern browsers supports the UrlSearchParams class.

    const query = new URLSearchParams('foo[]=bar&foo[]=baz&foo=1&foo=2');
    console.log(query.get('foo[]'));     // returns 'bar'
    console.log(query.getAll('foo[]'));  // returns ['bar', 'baz']
    console.log(query.get('foo'));       // returns ['1']
    console.log(query.getAll('foo'));    // returns ['1', '2']

• The parameter() method follow the PHP behaviour. Internally the query data are stored as pair to allow calculating both representations without data loss.

Because of the different storing technique when the query is rebuild:

• the original query string has been preserved with the UrlSearchParams algorithm, not in the case of parse_str and http_build_query.

But as you said and as I thought it is a bit off topics but it would have been nice to have this feature baked and present for developers to consume. By the way if you look at Guzzle for instance they are using a similar technique to avoid parse_str shortcomings (when you directly use the $_GET data you are also using parse_str.)

[romm]

Thank you for the example, I definitely learned something tonight.

Unfortunately I confirm this is out of scope with this topic… 😕

As I said earlier, I think the best we could do is to provide a section about this in the upcoming documentation chapter: maybe you could help when it comes?

[eigan]

We went with option A

    /**
     * @param int $instanceId
     * @param array{foo: string} $query
     * @param array{bar: int} $payload
     * @return void
     */
    #[Route('/system/execute_task/{instanceId}')]
    public function executeTask(
        #[MapRouteParameter] int $instanceId,
        #[MapQueryString] array $query,
        #[MapRequestPayload] array $payload)
    {}

Solved by looking at the signature of the controller method, and passing to valinor if MapQueryString or MapRequestPayload is used. MapQueryString has allowScalarValueCasting.

To be able to use the @param array in docblock did we have to copy your ParameterTypeResolver::extractTypeFromDocBlock() 👼🏻

For MapRouteParameter we use data from our router (symfony/router): $this->router->match($requestUri->getPath()).

I like when I can control everything from the controller and not have to modify something at root-level.

[romm]

Hi everyone! I've just submitted two pull requests to try out the HTTP request mapping feature. The development is not completely over yet, but most of it has been done.

• First Pull Request #747 is an implementation of option E that was discussed in this thread. It allows HTTP request mapping based on the method of the request (basically, a GET request will use query parameters for the mapping whereas a POST request will use the body payload).
• Second Pull Request #748 overwrites the first one by adding attributes support for the mapping, which also changes the behavior as you can have both query parameters and body mapped.

I'd really like to have some feedback on this — not necessarily a code-review (although it is always welcome 😊) — if you could try it out in your projects, see what's wrong and get back to me, that would be awesome.

⚠️ One of the missing part is handling "single value" mapping, aka mapping a whole query/body to a single DTO/array parameter. This is on the todo-list and will probably land in the upcoming days!

Having these feedback will help taking a decision on which approach will be included in the library's core. Thank you in advance. 😊

[eigan]

@romm Did some testing with #748. Found a couple things which would be nice-to-have 🙂

1. I sometimes drop creating DTOs for simple structures. Sharing those structures between methods would be nice.

/**
  * @phpstan-type Payload array{id: int, name: string}
  */
class Controller {
   /**
    * @param Payload $payload
    */
   public function method1(#[FromBody] array $payload) {}
}

2. Could it silently ignore un-mappable parameters?

Uncaught CuyZ\Valinor\Mapper\Tree\Exception\CannotMapHttpRequestElement: Element `entityManager` is not bound to a route parameter and is not tagged with a `#[FromQuery]` nor a `#[FromBody]` attribute. in /srv/plusoffice/hms/versions/dev/vendor/cuyz/valinor/src/Mapper/Tree/Builder/HttpRequestNodeBuilder.php:104

class Controller {
   public function method1(#[FromBody] SomeDto $payload, EntityManager $entityManager) {}
}

[romm]

Hi @eigan, thank you very much for your valuable feedback 🙏 — There is still a bit of work before I can merge this feature, but this should be coming pretty soon 🤞

@romm Did some testing with #748. Found a couple things which would be nice-to-have 🙂

1. I sometimes drop creating DTOs for simple structures. Sharing those  structures between methods would be nice.

/**
  * @phpstan-type Payload array{id: int, name: string}
  */
class Controller {
   /**
    * @param Payload $payload
    */
   public function method1(#[FromBody] array $payload) {}
}

This should already work when using #[FromBody(mapAll: true)] but I believe there is a bug with the @phpstan-type parsing when using it on a method parameter. So I need to fix that bug in order for this code to work, but this is not related to the HTTP request mapping feature. 😊

2. Could it silently ignore un-mappable parameters?

Uncaught CuyZ\Valinor\Mapper\Tree\Exception\CannotMapHttpRequestElement: Element `entityManager` is not bound to a route parameter and is not tagged with a `#[FromQuery]` nor a `#[FromBody]` attribute. in /srv/plusoffice/hms/versions/dev/vendor/cuyz/valinor/src/Mapper/Tree/Builder/HttpRequestNodeBuilder.php:104

class Controller {
   public function method1(#[FromBody] SomeDto $payload, EntityManager $entityManager) {}
}

I've already been thinking about this, and for now I see no robust solution to this problem without introducing a very opinionated system. I understand this can be very convenient, but it also kind of collides with the core feature — which is raw user input mapping — by introducing a dependency injection feature. So I think there is very little chance that this is part of the feature release; but who knows maybe I'll think about something until then 🤷

[eigan]

Maybe it would be possible to wait with the exception until all elements have been processed. Then send the successful elements as part of the exception. So you could ignore the exception if you would like 🤔 IncompleteArgumentMapException.

Or maybe i should just rethink how I create controller methods 😆

---

Hm, mapAll, didnt see that for some reason 🙂
I don't think I have ever had the need to pick just some parts of the query or payload. I always want to map everything to a $query or $payload param. So i guess I would need to add mapAll: true everywhere.

[romm]

One thing to note is that it should also be possible to let your framework inject the Request(Interface?) object in your controller, and you should be able to directly map this object to a DTO.

Something like:

final class MyController
{
    public function __construct(
        private TreeMapper $mapper,
    ) {}

    public function __invoke(RequestInterface $request, TreeMapper $mapper): Response
    {
        $requestDTO = $mapper->map(SomeDTO::class, $request);
    }
}

This is not the most convenient way, and a downside is that you wont be able to map to a shaped array, because you need the property/parameters attributes (#[FromBody], etc.) to be present.

May I ask which framework you usually use?

[eigan]

Legacy software, no framework - but use psr, and symfony components.
Today we map to DTO/array shapes thanks to Valinor, using reflections to inspect the signature. Defining the entire request object in a single method parameter makes it easier to understand what it accepts, and we can respond with HTTP 422 before even calling the controller method - reducing some boilerplate. Its also lets us create openapi spec automatically.

While it kinda-of works today - I look forward to whatever you come up with, and we will use it if it can replace our code, as your stuff is way better than mine 😄

[romm]

Hi everyone, thanks a lot for the very interesting discussions we had here.

The HTTP request mapping feature has just been released in 2.4.0.

Hope you'll enjoy it!