Description

Currently Symfony provides natively @Route an @Method annotations to map requests to controllers. In addition, it injects automatically request attributes to controller in a convenient way. I think that it could be improved to inject another request data through annotations. I know that this can be accomplished through ParamConverters, but I see that feature as a generic way to inject any type of information to controllers (e.g DateTime). The examples bellow shows exactly what I'm proposing to be part of Symfony's Core.

One of the benefits of this proposal is this more expressive and transparent to newcomers instead of ParamConverters.

Please, don't miss understand this proposal as this is not a replace to ParamConverters. Is just to add specific annotations to deal with request data. It means that DateTime, granted user and etc will be converter through ParamConverter as well as dev's custom converters.

Proposal

Request Body

• Pass the request content to $content variable.

/**  
 * @RequestBody("content") 
 */
 public function show(string $content) {}  

All the bellow examples uses only one argument in controllers, so omitting the argument 
name from annotation will work properly. Otherwise, the argument name should be provided.

• A Bad Request exception will be thrown if the request content is empty if the argument is required. If the content is optional, you can make your argument to allow null and the exception will not be raised. The same principle will work for all converters.

 /** 
  * @RequestBody() 
  */
  public function show(?string $content) {}

• If the request is a JSON/XML content (e.g the headers has application/[json/xml]) the converter will decode the content and pass it to controller. If the json/xml passed is mal formed, the proper http status code could be thrown automatically.

/**  
 * @RequestBody()
 */
 public function show(array $post) {}  

• If the argument is type-hinted to some complex type, the converter will deserialize the content and inject the result automatically. FOS has an annotation that makes this, but I think it could be part of Symfony's core.

/**  
 * @RequestBody() 
 */
 public function show(Post $post) {}  

Query Param

• Inject a single query param when the route /foo?foo=bar is matched.

/**  
 * @QueryParam() 
 */
 public function show(string $foo) { echo $foo; // will echo "bar"}  

• Default value if the query param isn't passed.

/**  
 * @QueryParam() 
 */
 public function show(string $foo = 'bar') {}

• Inject two query params

/**  
 * @QueryParam("foo")
 * @QueryParam("bar") 
 */
 public function show(string $foo, string $bar) {}  

• Inject all query params as ParameterBag instance

/**  
 * @QueryParam()
 */
 public function show(ParameterBag $query) {}  

• Inject all query params as plain array

/**  
 * @QueryParam(all=true)
 */
 public function show(array $query) {}  

• Inject a complex type from query param

/**  
 * @Route("/posts?id=1")
 * @QueryParam()
 */
 public function show(Post $post) {}  

Request Header

• Inject a single header

/**  
 * @RequestHeader(name="Content-Type") 
 */
 public function show(string $contentType) { }  

• Default value if the header isn't passed.

/**  
 * @RequestHeader() 
 */
 public function show(string $contentType = 'application/json') {}

• Inject two headers

/**  
 * @RequestHeader("userId", name="X-USER-ID")
 * @RequestHeader("userAgent", name="User-Agent") 
 */
 public function show(string $userId, string $userAgent) {}  

• Inject all headers as HeaderBag

/**  
 * @RequestHeader(all=true)
 */
 public function show(HeaderBag $headers) {}  

• Inject a complex type from header

/** 
 * @RequestHeader(name="X-POST-ID")
 */
 public function show(Post $post) {}