From daa912ddfb22d5cb160818da1352bc45cb068d2f Mon Sep 17 00:00:00 2001
From: Steven Renaux <steven.renaux@sensiolabs.com>
Date: Tue, 7 Jan 2025 15:21:32 +0100
Subject: [PATCH] Add MapRequestHeader doc

---
 controller.rst | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)

diff --git a/controller.rst b/controller.rst
index c11615d93aa..6f2369384ba 100644
--- a/controller.rst
+++ b/controller.rst
@@ -688,6 +688,93 @@ there are constraint violations:
 
     The ``#[MapUploadedFile]`` attribute was introduced in Symfony 7.1.
 
+Mapping Header Individually
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes, you need to retrieve one or more headers from an HTTP request to handle
+specific logic in your application.
+Thanks to the :class:`Symfony\\Component\\HttpKernel\\Attribute\\MapRequestHeader`
+attribute, arguments of your controller's action can be automatically fulfilled::
+
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Attribute\MapRequestHeader;
+
+    // ...
+
+    public function dashboard(
+        #[MapRequestHeader] string $accept
+    ): Response
+    {
+        // ...
+    }
+
+``#[MapRequestHeader]`` can take an optional argument called ``name``.
+This argument helps you when the parameter can't be determine by the variable name
+itself.
+
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Attribute\MapRequestHeader;
+
+    // ...
+
+    public function dashboard(
+        #[MapRequestHeader(name: 'user-agent')] ?string $agent,
+    ): Response
+    {
+        // ...
+    }
+
+If we are looking for a header of type Accept-* with an array type, we will use
+the `dedicated methods`_  to retrieve this data.
+
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Attribute\MapRequestHeader;
+
+    // ...
+
+    public function dashboard(
+        #[MapRequestHeader] array $accept,
+    ): Response
+    {
+        // ...
+    }
+
+The last possible return type is to use the :class:`Symfony\\Component\\HttpFoundation\\AcceptHeader`
+
+    use Symfony\Component\HttpFoundation\AcceptHeader;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Attribute\MapRequestHeader;
+
+    // ...
+
+    public function dashboard(
+        #[MapRequestHeader(name: 'accept-encoding')] AcceptHeader $encoding,
+    ): Response
+    {
+        // ...
+    }
+
+You can customize the HTTP status to return if the validation fails:
+
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Attribute\MapRequestHeader;
+
+    // ...
+
+    public function dashboard(
+        #[MapRequestHeader(validationFailedStatusCode: Response::HTTP_UNPROCESSABLE_ENTITY)] ?string $agent,
+    ): Response
+    {
+        // ...
+    }
+
+The default status code returned if the validation fails is 400.
+
+.. versionadded:: 7.1
+
+    The :class:`Symfony\\Component\\HttpKernel\\Attribute\\apRequestHeader` attribute
+    was introduced in Symfony 7.1.
+
 Managing the Session
 --------------------
 
@@ -957,3 +1044,4 @@ Learn more about Controllers
 .. _`Validate Filters`: https://www.php.net/manual/en/filter.constants.php
 .. _`phpstan/phpdoc-parser`: https://packagist.org/packages/phpstan/phpdoc-parser
 .. _`phpdocumentor/type-resolver`: https://packagist.org/packages/phpdocumentor/type-resolver
+.. _`dedicated methods`: https://symfony.com/doc/current/components/http_foundation.html#accessing-accept-headers-data