From 43355162a8cce5c794299e6d359a8a436929c067 Mon Sep 17 00:00:00 2001
From: Rene Lima <renedelima@gmail.com>
Date: Fri, 19 Apr 2024 20:28:09 +0200
Subject: [PATCH] Add documentation for #[MapUploadedFile] attribute

---
 controller.rst           | 93 ++++++++++++++++++++++++++++++++++++++++
 reference/attributes.rst |  1 +
 2 files changed, 94 insertions(+)

diff --git a/controller.rst b/controller.rst
index 90277e07b76..f0cac7b2350 100644
--- a/controller.rst
+++ b/controller.rst
@@ -587,6 +587,99 @@ using the ``type`` option of the attribute::
 
     The ``type`` option of ``#[MapRequestPayload]`` was introduced in Symfony 7.1.
 
+.. _controller_map-uploaded-file:
+
+Mapping Uploaded File
+~~~~~~~~~~~~~~~~~~~~~
+
+You can map ``UploadedFile``s to the controller arguments and optionally bind ``Constraints`` to them.
+The argument resolver fetches the ``UploadedFile`` based on the argument name.
+
+::
+
+    namespace App\Controller;
+
+    use Symfony\Component\HttpFoundation\File\UploadedFile;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Attribute\MapUploadedFile;
+    use Symfony\Component\Routing\Attribute\Route;
+    use Symfony\Component\Validator\Constraints as Assert;
+
+    #[Route('/user/picture', methods: ['PUT'])]
+    class ChangeUserPictureController
+    {
+        public function _invoke(
+            #[MapUploadedFile([
+                new Assert\File(mimeTypes: ['image/png', 'image/jpeg']),
+                new Assert\Image(maxWidth: 3840, maxHeight: 2160)
+            ])]
+            UploadedFile $picture
+        ): Response {
+            // ...
+        }
+    }
+
+.. tip::
+
+    The bound ``Constraints`` are performed before injecting the ``UploadedFile`` into the controller argument.
+    When a constraint violation is detected an ``HTTPException`` is thrown and the controller's
+    action is not executed.
+
+Mapping ``UploadedFile``s with no custom settings.
+
+.. code-block:: php-attributes
+
+    #[MapUploadedFile]
+    UploadedFile $document
+
+An ``HTTPException`` is thrown when the file is not submitted.
+You can skip this check by making the controller argument nullable.
+
+.. code-block:: php-attributes
+
+    #[MapUploadedFile]
+    ?UploadedFile $document
+
+.. code-block:: php-attributes
+
+    #[MapUploadedFile]
+    UploadedFile|null $document
+
+``UploadedFile`` collections must be mapped to array or variadic arguments.
+The bound ``Constraints`` will be applied to each file in the collection.
+If a constraint violation is detected to one of them an ``HTTPException`` is thrown.
+
+.. code-block:: php-attributes
+
+    #[MapUploadedFile(new Assert\File(mimeTypes: ['application/pdf']))]
+    array $documents
+
+.. code-block:: php-attributes
+
+    #[MapUploadedFile(new Assert\File(mimeTypes: ['application/pdf']))]
+    UploadedFile ...$documents
+
+Handling custom names.
+
+.. code-block:: php-attributes
+
+    #[MapUploadedFile(name: 'something-else')]
+    UploadedFile $document
+
+Changing the ``HTTP Status`` thrown when constraint violations are detected.
+
+.. code-block:: php-attributes
+
+    #[MapUploadedFile(
+        constraints: new Assert\File(maxSize: '2M'),
+        validationFailedStatusCode: Response::HTTP_REQUEST_ENTITY_TOO_LARGE
+    )]
+    UploadedFile $document
+
+.. versionadded:: 7.1
+
+    The ``#[MapUploadedFile]`` attribute was introduced in Symfony 7.1.
+
 Managing the Session
 --------------------
 
diff --git a/reference/attributes.rst b/reference/attributes.rst
index a1e8532c347..4428dc4c587 100644
--- a/reference/attributes.rst
+++ b/reference/attributes.rst
@@ -64,6 +64,7 @@ HttpKernel
 * :ref:`MapQueryParameter <controller_map-request>`
 * :ref:`MapQueryString <controller_map-request>`
 * :ref:`MapRequestPayload <controller_map-request>`
+* :ref:`MapUploadedFile <controller_map-uploaded-file>`
 * :ref:`ValueResolver <managing-value-resolvers>`
 * :ref:`WithHttpStatus <framework_exceptions>`
 * :ref:`WithLogLevel <framework_exceptions>`