Add documentation for #[MapUploadedFile] attribute

renedelima · renedelima · commit 15e622cc7249 · 2024-04-20T11:20:26.000+02:00
diff --git a/controller.rst b/controller.rst
@@ -587,6 +587,94 @@ using the ``type`` option of the attribute::
 
     The ``type`` option of ``#[MapRequestPayload]`` was introduced in Symfony 7.1.
 
+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 its name.
+
+.. code-block:: php-attributes
+
+    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 UserPictureController
+    {
+        public function _invoke(
+            #[MapUploadedFile(new Assert\File(mimeTypes: ['image/png', 'image/jpeg']))]
+            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
 --------------------
 
