file upload use processor instead of controller (#1947)

Author: soyuka

core/file-upload.md

@@ -11,6 +11,23 @@ before proceeding. It will help you get a grasp on how the bundle works, and why
 **Note**: Uploading files won't work in `PUT` or `PATCH` requests, you must use `POST` method to upload files.
 See [the related issue on Symfony](https://github.com/symfony/symfony/issues/9226) and [the related bug in PHP](https://bugs.php.net/bug.php?id=55815) talking about this behavior.
 
+Previously to API Platform 3.3, file upload was using controllers that needs: 
+
+```yaml
+api_platform:
+    use_symfony_listeners: true
+```
+
+Since 3.3, we recommend to use a Processor, note that you need to enable the multipart format globally: 
+
+```yaml
+api_platform:
+    use_symfony_listeners: false
+    formats:
+        multipart: ['multipart/form-data']
+        jsonld: ['application/ld+json']
+```
+
 ## Installing VichUploaderBundle
 
 Install the bundle with the help of Composer:
@@ -63,7 +80,7 @@ use ApiPlatform\Metadata\Get;
 use ApiPlatform\Metadata\GetCollection;
 use ApiPlatform\Metadata\Post;
 use ApiPlatform\OpenApi\Model;
-use App\Controller\CreateMediaObjectAction;
+use App\State\SaveMediaObject;
 use Doctrine\ORM\Mapping as ORM;
 use Symfony\Component\HttpFoundation\File\File;
 use Symfony\Component\Serializer\Annotation\Groups;
@@ -75,12 +92,13 @@ use Vich\UploaderBundle\Mapping\Annotation as Vich;
 #[ApiResource(
     normalizationContext: ['groups' => ['media_object:read']], 
     types: ['https://schema.org/MediaObject'],
+    outputFormats: ['jsonld' => ['application/ld+json']],
     operations: [
         new Get(),
         new GetCollection(),
         new Post(
             inputFormats: ['multipart' => ['multipart/form-data']],
-            controller: CreateMediaObjectAction::class, 
+            processor: SaveMediaObject::class,
             deserialize: false, 
             validationContext: ['groups' => ['Default', 'media_object_create']], 
             openapi: new Model\Operation(
@@ -127,37 +145,41 @@ class MediaObject
 ```
 Note: From V3.3 onwards, `'multipart/form-data'` must either be including in the global API-Platform config, either in `formats` or `defaults->inputFormats`, or defined as an `inputFormats` parameter on an operation by operation basis.
 
-### Creating the Controller
+### Creating the Processor
 
-At this point, the entity is configured, but we still need to write the action
+At this point, the entity is configured, but we still need to write the processor
 that handles the file upload.
 
 ```php
 <?php
-// api/src/Controller/CreateMediaObjectAction.php
+// api/src/State/SaveMediaObject.php
 
-namespace App\Controller;
+namespace App\State;
 
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProcessorInterface;
 use App\Entity\MediaObject;
-use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-use Symfony\Component\HttpFoundation\Request;
-use Symfony\Component\HttpKernel\Attribute\AsController;
+use Symfony\Component\DependencyInjection\Attribute\Autowire;
 use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
+use Vich\UploaderBundle\Storage\StorageInterface;
 
-#[AsController]
-final class CreateMediaObjectAction extends AbstractController
+final class SaveMediaObject implements ProcessorInterface
 {
-    public function __invoke(Request $request): MediaObject
+    public function __construct(
+        #[Autowire('@api_platform.doctrine.orm.state.persist_processor')] private readonly ProcessorInterface $processor,
+        private readonly StorageInterface $storage
+    ) {}
+
+    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = [])
     {
-        $uploadedFile = $request->files->get('file');
+        $uploadedFile = $context['request']->files->get('file');
         if (!$uploadedFile) {
             throw new BadRequestHttpException('"file" is required');
         }
 
         $mediaObject = new MediaObject();
         $mediaObject->file = $uploadedFile;
-
-        return $mediaObject;
+        return $this->processor->process($mediaObject, $operation, $uriVariables, $context);
     }
 }
 ```
@@ -185,7 +207,7 @@ class MediaObjectNormalizer implements NormalizerInterface
   private const ALREADY_CALLED = 'MEDIA_OBJECT_NORMALIZER_ALREADY_CALLED';
 
   public function __construct(
-    #[Autowire(service: 'serializer.normalizer.object')]
+    #[Autowire(service: 'api_platform.jsonld.normalizer.item')]
     private readonly NormalizerInterface $normalizer,
     private readonly StorageInterface $storage
   ) {
@@ -385,7 +407,10 @@ use Vich\UploaderBundle\Mapping\Annotation as Vich;
     types: ['https://schema.org/Book'],
     operations: [
         new GetCollection(),
-        new Post(inputFormats: ['multipart' => ['multipart/form-data']])
+        new Post(
+            outputFormats: ['jsonld' => ['application/ld+json']],
+            inputFormats: ['multipart' => ['multipart/form-data']]
+        )
     ]
 )]
 class Book