@@ -589,84 +589,91 @@ using the ``type`` option of the attribute::
589
589
590
590
.. _controller_map-uploaded-file :
591
591
592
- Mapping Uploaded File
593
- ~~~~~~~~~~~~~~~~~~~~~
592
+ Mapping Uploaded Files
593
+ ~~~~~~~~~~~~~~~~~~~~~~
594
594
595
- You can map ``UploadedFile``s to the controller arguments and optionally bind ``Constraints `` to them.
596
- The argument resolver fetches the ``UploadedFile `` based on the argument name.
597
-
598
- ::
595
+ Symfony provides an attribute called ``#[MapUploadedFile] `` to map one or more
596
+ ``UploadedFile `` objects to controller arguments::
599
597
600
598
namespace App\Controller;
601
599
600
+ use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
602
601
use Symfony\Component\HttpFoundation\File\UploadedFile;
603
602
use Symfony\Component\HttpFoundation\Response;
604
603
use Symfony\Component\HttpKernel\Attribute\MapUploadedFile;
605
604
use Symfony\Component\Routing\Attribute\Route;
606
- use Symfony\Component\Validator\Constraints as Assert;
607
605
608
- #[Route('/user/picture', methods: ['PUT'])]
609
- class ChangeUserPictureController
606
+ class UserController extends AbstractController
610
607
{
611
- public function _invoke(
612
- #[MapUploadedFile([
613
- new Assert\File(mimeTypes: ['image/png', 'image/jpeg']),
614
- new Assert\Image(maxWidth: 3840, maxHeight: 2160)
615
- ])]
616
- UploadedFile $picture
608
+ #[Route('/user/picture', methods: ['PUT'])]
609
+ public function changePicture(
610
+ #[MapUploadedFile] UploadedFile $picture,
617
611
): Response {
618
612
// ...
619
613
}
620
614
}
621
615
622
- .. tip ::
623
-
624
- The bound ``Constraints `` are performed before injecting the ``UploadedFile `` into the controller argument.
625
- When a constraint violation is detected an ``HTTPException `` is thrown and the controller's
626
- action is not executed.
627
-
628
- Mapping ``UploadedFile``s with no custom settings.
616
+ In this example, the associated :doc: `argument resolver <controller/value_resolver >`
617
+ fetches the ``UploadedFile `` based on the argument name (``$picture ``). If no file
618
+ is submitted, an ``HttpException `` is thrown. You can change this by making the
619
+ controller argument nullable:
629
620
630
621
.. code-block :: php-attributes
631
622
632
623
#[MapUploadedFile]
633
- UploadedFile $document
624
+ ? UploadedFile $document
634
625
635
- An ``HTTPException `` is thrown when the file is not submitted.
636
- You can skip this check by making the controller argument nullable.
626
+ The ``#[MapUploadedFile] `` attribute also allows to pass a list of constraints
627
+ to apply to the uploaded file::
637
628
638
- .. code-block :: php-attributes
629
+ namespace App\Controller;
639
630
640
- #[MapUploadedFile]
641
- ?UploadedFile $document
631
+ use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
632
+ use Symfony\Component\HttpFoundation\File\UploadedFile;
633
+ use Symfony\Component\HttpFoundation\Response;
634
+ use Symfony\Component\HttpKernel\Attribute\MapUploadedFile;
635
+ use Symfony\Component\Routing\Attribute\Route;
636
+ use Symfony\Component\Validator\Constraints as Assert;
642
637
643
- .. code-block :: php-attributes
638
+ class UserController extends AbstractController
639
+ {
640
+ #[Route('/user/picture', methods: ['PUT'])]
641
+ public function changePicture(
642
+ #[MapUploadedFile([
643
+ new Assert\File(mimeTypes: ['image/png', 'image/jpeg']),
644
+ new Assert\Image(maxWidth: 3840, maxHeight: 2160),
645
+ ])]
646
+ UploadedFile $picture,
647
+ ): Response {
648
+ // ...
649
+ }
650
+ }
644
651
645
- #[MapUploadedFile]
646
- UploadedFile|null $document
652
+ The validation constraints are checked before injecting the ``UploadedFile `` into
653
+ the controller argument. If there's a constraint violation, an ``HttpException ``
654
+ is thrown and the controller's action is not executed.
647
655
648
- `` UploadedFile `` collections must be mapped to array or variadic arguments.
649
- The bound `` Constraints `` will be applied to each file in the collection.
650
- If a constraint violation is detected to one of them an ``HTTPException `` is thrown.
656
+ If you need to upload a collection of files, map them to an array or a variadic
657
+ argument. The given constraint will be applied to all files and if any of them
658
+ fails, an ``HttpException `` is thrown:
651
659
652
660
.. code-block :: php-attributes
653
661
654
662
#[MapUploadedFile(new Assert\File(mimeTypes: ['application/pdf']))]
655
663
array $documents
656
664
657
- .. code-block :: php-attributes
658
-
659
665
#[MapUploadedFile(new Assert\File(mimeTypes: ['application/pdf']))]
660
666
UploadedFile ...$documents
661
667
662
- Handling custom names.
668
+ Use the `` name `` option to rename the uploaded file to a custom value:
663
669
664
670
.. code-block :: php-attributes
665
671
666
672
#[MapUploadedFile(name: 'something-else')]
667
673
UploadedFile $document
668
674
669
- Changing the ``HTTP Status `` thrown when constraint violations are detected.
675
+ In addition, you can change the status code of the HTTP exception thrown when
676
+ there are constraint violations:
670
677
671
678
.. code-block :: php-attributes
672
679
0 commit comments