Skip to content

Commit 846cbae

Browse files
committed
Tweaks and rewords
1 parent 630cac8 commit 846cbae

File tree

1 file changed

+45
-38
lines changed

1 file changed

+45
-38
lines changed

controller.rst

Lines changed: 45 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -589,84 +589,91 @@ using the ``type`` option of the attribute::
589589

590590
.. _controller_map-uploaded-file:
591591

592-
Mapping Uploaded File
593-
~~~~~~~~~~~~~~~~~~~~~
592+
Mapping Uploaded Files
593+
~~~~~~~~~~~~~~~~~~~~~~
594594

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::
599597

600598
namespace App\Controller;
601599

600+
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
602601
use Symfony\Component\HttpFoundation\File\UploadedFile;
603602
use Symfony\Component\HttpFoundation\Response;
604603
use Symfony\Component\HttpKernel\Attribute\MapUploadedFile;
605604
use Symfony\Component\Routing\Attribute\Route;
606-
use Symfony\Component\Validator\Constraints as Assert;
607605

608-
#[Route('/user/picture', methods: ['PUT'])]
609-
class ChangeUserPictureController
606+
class UserController extends AbstractController
610607
{
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,
617611
): Response {
618612
// ...
619613
}
620614
}
621615

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:
629620

630621
.. code-block:: php-attributes
631622
632623
#[MapUploadedFile]
633-
UploadedFile $document
624+
?UploadedFile $document
634625
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::
637628

638-
.. code-block:: php-attributes
629+
namespace App\Controller;
639630

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;
642637

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+
}
644651

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.
647655

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:
651659

652660
.. code-block:: php-attributes
653661
654662
#[MapUploadedFile(new Assert\File(mimeTypes: ['application/pdf']))]
655663
array $documents
656664
657-
.. code-block:: php-attributes
658-
659665
#[MapUploadedFile(new Assert\File(mimeTypes: ['application/pdf']))]
660666
UploadedFile ...$documents
661667
662-
Handling custom names.
668+
Use the ``name`` option to rename the uploaded file to a custom value:
663669

664670
.. code-block:: php-attributes
665671
666672
#[MapUploadedFile(name: 'something-else')]
667673
UploadedFile $document
668674
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:
670677

671678
.. code-block:: php-attributes
672679

0 commit comments

Comments
 (0)