From 43355162a8cce5c794299e6d359a8a436929c067 Mon Sep 17 00:00:00 2001 From: Rene Lima 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 ` * :ref:`MapQueryString ` * :ref:`MapRequestPayload ` +* :ref:`MapUploadedFile ` * :ref:`ValueResolver ` * :ref:`WithHttpStatus ` * :ref:`WithLogLevel ` pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.

Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy