Skip to content

Commit 2760f35

Browse files
committed
Add documentation for #[MapUploadedFile] attribute
1 parent 53a1966 commit 2760f35

File tree

1 file changed

+92
-0
lines changed

1 file changed

+92
-0
lines changed

controller.rst

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -587,6 +587,98 @@ using the ``type`` option of the attribute::
587587

588588
The ``type`` option of ``#[MapRequestPayload]`` was introduced in Symfony 7.1.
589589

590+
Mapping Uploaded File
591+
~~~~~~~~~~~~~~~~~~~~~
592+
593+
You can map ``UploadedFile``s to the controller arguments and optionally bind ``Constraints`` to them.
594+
The argument resolver fetches the ``UploadedFile`` based on the argument name.
595+
596+
.. code-block:: php
597+
598+
namespace App\Controller;
599+
600+
use Symfony\Component\HttpFoundation\File\UploadedFile;
601+
use Symfony\Component\HttpFoundation\Response;
602+
use Symfony\Component\HttpKernel\Attribute\MapUploadedFile;
603+
use Symfony\Component\Routing\Attribute\Route;
604+
use Symfony\Component\Validator\Constraints as Assert;
605+
606+
#[Route('/user/picture', methods: ['PUT'])]
607+
class ChangeUserPictureController
608+
{
609+
public function _invoke(
610+
#[MapUploadedFile([
611+
new Assert\File(mimeTypes: ['image/png', 'image/jpeg']),
612+
new Assert\Image(maxWidth: 3840, maxHeight: 2160)
613+
])]
614+
UploadedFile $picture
615+
): Response {
616+
// ...
617+
}
618+
}
619+
620+
.. tip::
621+
622+
The bound ``Constraints`` are performed before injecting the ``UploadedFile`` into the controller argument.
623+
When a constraint violation is detected an ``HTTPException`` is thrown and the controller's
624+
action is not executed.
625+
626+
Mapping ``UploadedFile``s with no custom settings.
627+
628+
.. code-block:: php
629+
630+
#[MapUploadedFile]
631+
UploadedFile $document
632+
633+
An ``HTTPException`` is thrown when the file is not submitted.
634+
You can skip this check by making the controller argument nullable.
635+
636+
.. code-block:: php
637+
638+
#[MapUploadedFile]
639+
?UploadedFile $document
640+
641+
.. code-block:: php
642+
643+
#[MapUploadedFile]
644+
UploadedFile|null $document
645+
646+
``UploadedFile`` collections must be mapped to array or variadic arguments.
647+
The bound ``Constraints`` will be applied to each file in the collection.
648+
If a constraint violation is detected to one of them an ``HTTPException`` is thrown.
649+
650+
.. code-block:: php
651+
652+
#[MapUploadedFile(new Assert\File(mimeTypes: ['application/pdf']))]
653+
array $documents
654+
655+
656+
.. code-block:: php
657+
658+
#[MapUploadedFile(new Assert\File(mimeTypes: ['application/pdf']))]
659+
UploadedFile ...$documents
660+
661+
Handling custom names.
662+
663+
.. code-block:: php
664+
665+
#[MapUploadedFile(name: 'something-else')]
666+
UploadedFile $document
667+
668+
Changing the ``HTTP Status`` thrown when constraint violations are detected.
669+
670+
.. code-block:: php
671+
672+
#[MapUploadedFile(
673+
constraints: new Assert\File(maxSize: '2M'),
674+
validationFailedStatusCode: Response::HTTP_REQUEST_ENTITY_TOO_LARGE
675+
)]
676+
UploadedFile $document
677+
678+
.. versionadded:: 7.1
679+
680+
The ``#[MapUploadedFile]`` attribute was introduced in Symfony 7.1.
681+
590682
Managing the Session
591683
--------------------
592684

0 commit comments

Comments
 (0)