fix #1856

Author: soyuka

core/bootstrap.md

@@ -3,6 +3,10 @@
 You may want to run a minimal version of API Platform. This one file runs API Platform (without GraphQL, Eloquent, Doctrine MongoDB...).
 It requires the following Composer packages:
 
+> [!NOTE]
+> This documentation is outdated we're working on improving it, in the mean time we declare
+ most of the services manually in the [ApiPlatformProvider](https://github.com/api-platform/core/blob/64768a6a5b480e1b8e33c639fb28b27883c69b79/src/Laravel/ApiPlatformProvider.php) it can be source of inspiration.
+
 ```console
 composer require \
     api-platform/core \

core/form-data.md

@@ -16,128 +16,73 @@ of the framework.
 > If you're working with Laravel, refer to the [Laravel CSRF documentation](https://laravel.com/docs/csrf) to ensure
 > adequate protection against such attacks.
 
-In this tutorial, we will decorate the default `DeserializeListener` class to handle form data if applicable, and delegate to the built-in listener for other cases.
+## Configuration
 
-## Create your `FormRequestProcessorDecorator` processor
+First, you must register the form format and map it to the `application/x-www-form-urlencoded` MIME type in your API Platform configuration:  
 
-This decorator is able to denormalize posted form data to the target object. In case of other format, it fallbacks to the original [DeserializeListener](https://github.com/api-platform/core/blob/91dc2a4d6eeb79ea8dec26b41e800827336beb1a/src/Bridge/Symfony/Bundle/Resources/config/api.xml#L85-L91).
-
-```php
-<?php
-// api/src/State/FormRequestProcessorDecorator.php using Symfony or app/State/FormRequestProcessorDecorator.php using Laravel
-
-namespace App\State;
-
-use ApiPlatform\State\ProcessorInterface;
-use Symfony\Component\HttpFoundation\Request;
-use ApiPlatform\Metadata\Operation;
-use ApiPlatform\State\SerializerContextBuilderInterface;
-use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
-
-final class FormRequestProcessorDecorator implements ProcessorInterface
-{
-    public function __construct(
-        private readonly ProcessorInterface $decorated,
-        private readonly DenormalizerInterface $denormalizer,
-        private readonly SerializerContextBuilderInterface $serializerContextBuilder
-    ) {}
-
-    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
-    {
-        // If the content type is form data, we process it separately
-        if ('form' === $data->getContentType()) {
-            return $this->handleFormRequest($data);
-        }
-
-        // Delegate the processing to the original processor for other cases
-        return $this->decorated->process($data, $operation, $uriVariables, $context);
-    }
+```yaml
+# api\_platform.yaml  
+api_platform:  
+    formats:  
+        jsonld: ['application/ld+json']  
+        form: ['application/x-www-form-urlencoded']
+```
 
-    /**
-     * Handle form requests by deserializing the data into the correct entity
-     */
-    private function handleFormRequest(Request $request)
-    {
-        $attributes = $request->attributes->get('_api_attributes');
-        if (!$attributes) {
-            return null;
-        }
+## Creating a Decoder
 
-        $context = $this->serializerContextBuilder->createFromRequest($request, false, $attributes);
+The Symfony Serializer (used by API Platform) does not decode `application/x-www-form-urlencoded` by default. 
+You need to create a custom decoder that implements DecoderInterface to handle this format.  
 
-        // Deserialize the form data into an entity
-        $data = $request->request->all();
-        
-        return $this->denormalizer->denormalize($data, 'App\Entity\SomeEntity', null, $context);
-    }
-}
-```
+```php
+<?php  
+// src/Serializer/FormUrlEncodedDecoder.php
 
-Next, configure the `FormRequestProcessorDecorator` according to whether you're using Symfony or Laravel, as shown below:
+namespace App\Serializer;
 
-### Creating the Service Definition using Symfony
+use Symfony\Component\Serializer\Encoder\DecoderInterface;
 
-```yaml
-# api/config/services.yaml
-services:
-  # ...
-    App\State\FormRequestProcessorDecorator:
-        decorates: api_platform.state.processor
-        arguments:
-            $decorated: '@App\State\FormRequestProcessorDecorator.inner'
-            $denormalizer: '@serializer'
-            $serializerContextBuilder: '@api_platform.serializer.context_builder'
-        tags:
-            - { name: 'api_platform.state.processor' }
-```
+class FormUrlEncodedDecoder implements DecoderInterface  
+{  
+    public function decode(string $data, string $format, array $context = []): mixed  
+    {  
+        if (\!is_string($data)) {  
+            throw new \InvalidArgumentException('Data must be a string.');  
+        }
 
-### Registering a Decorated Processor using Laravel
+        parse_str($data, $parsedData);
 
-```php
-<?php
-// app/Providers/AppServiceProvider.php
-
-namespace App\Providers;
-
-use Illuminate\Support\ServiceProvider;
-use App\State\FormRequestProcessorDecorator;
-use ApiPlatform\State\ProcessorInterface;
-use ApiPlatform\State\SerializerContextBuilderInterface;
-use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
-
-class AppServiceProvider extends ServiceProvider
-{
-    public function register()
-    {
-        $this->app->bind(ProcessorInterface::class, function ($app) {
-            $decoratedProcessor = $app->make(ProcessorInterface::class); 
-
-            return new FormRequestProcessorDecorator(
-                $decoratedProcessor,
-                $app->make(DenormalizerInterface::class),
-                $app->make(SerializerContextBuilderInterface::class)
-            );
-        });
+        return $parsedData;  
     }
+
+    public function supportsDecoding(string $format): bool  
+    {  
+        return $format === 'form';  
+    }  
 }
 ```
 
-## Using your `FormRequestProcessorDecorator` processor
+## **Usage in a Resource**
 
-Finally, you can use the processor in your API Resource like this:
+You can now configure your API Resource to accept the form input format. In this example, we define a FormData resource and restrict the inputFormats for the Post operation.  
 
 ```php
-<?php
-// api/src/ApiResource/SomeEntity.php with Symfony or app/ApiResource/SomeEntity.php with Laravel
+<?php  
+// src/ApiResource/FormData.php
 
 namespace App\ApiResource;
 
+use ApiPlatform\Metadata\Operation;  
 use ApiPlatform\Metadata\Post;
-use App\State\FormRequestProcessorDecorator;
 
-#[Post(processor: FormRequestProcessorDecorator::class)]
-class SomeEntity
-{
-    //...
-}
+#[Post(  
+    inputFormats: ['form' => ['application/x-www-form-urlencoded']],  
+    processor: [self::class, 'process']  
+)]  
+class FormData {  
+    public string $name;
+
+    public static function process(mixed $data, Operation $operation, array $uriVariables, array $context) {  
+        return $data;  
+    }  
+}  
 ```