Merge pull request #768 from soyuka/document-messenger-input

Document messenger input

Author: soyuka

core/messenger.md

@@ -53,7 +53,7 @@ Because the `messenger` attribute is `true`, when a `POST` is handled by API Pla
 For this example, only the `POST` operation is enabled.
 We use the `status` attribute to configure API Platform to return a [202 Accepted HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202).
 It indicates that the request has been received and will be treated later, without giving an immediate return to the client.
-Finally, the `output` attribute is set to `false`, so the HTTP response that will be generated by API Platform will be empty, and the [serialization process](serialization.md) will be skipped. 
+Finally, the `output` attribute is set to `false`, so the HTTP response that will be generated by API Platform will be empty, and the [serialization process](serialization.md) will be skipped.
 
 ## Registering a Message Handler
 
@@ -92,3 +92,79 @@ It means that if you use a synchronous handler, the data returned by the `__invo
 
 When a `DELETE` operation occurs, API Platform automatically adds a `ApiPlatform\Core\Bridge\Symfony\Messenger\RemoveStamp` ["stamp"](https://symfony.com/doc/current/components/messenger.html#adding-metadata-to-messages-envelopes) instance to the "envelope".
 To differentiate typical persists calls (create and update) and removal calls, check for the presence of this stamp using [a custom "middleware"](https://symfony.com/doc/current/components/messenger.html#adding-metadata-to-messages-envelopes).
+
+## Using Messenger with an Input Object
+
+Set the `messenger` attribute to `input`, and API Platform will automatically dispatch the given Input as a message instead of the Resource. Indeed, it'll add a default `DataTransformer` ([see input/output documentation](./dto.md)) that handles the given `input`.
+
+```php
+<?php
+
+// api/src/Entity/User.php
+
+namespace App\Entity;
+
+use ApiPlatform\Core\Annotation\ApiResource;
+use App\Dto\ResetPasswordRequest;
+
+/**
+ * @ApiResource(
+ *     collectionOperations={
+ *         "post"={"status"=202}
+ *     },
+ *     itemOperations={},
+ *     messenger=true,
+ *     input=ResetPasswordRequest::class,
+ *     output=false
+ * )
+ */
+final class User
+{
+}
+```
+
+Where `ResetPasswordRequest` would be:
+
+```php
+<?php
+
+// api/src/Dto/ResetPasswordRequest.php
+
+namespace App\Dto;
+use Symfony\Component\Validator\Constraints as Assert;
+
+final class ResetPasswordRequest
+{
+    /**
+     * @var string
+     * @Assert\NotBlank
+     */
+    public $var;
+}
+```
+
+For this example, only the `POST` operation is enabled on `/users`.
+As above, we use the `status` attribute to configure API Platform to return a [202 Accepted HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202).
+It indicates that the request has been received and will be treated later, without giving an immediate return to the client.
+Finally, the `output` attribute is set to `false`, so the HTTP response that will be generated by API Platform will be empty, and the [serialization process](serialization.md) will be skipped.
+
+In this case, when a `POST` request is issued on `/users` the message handler will receive an `App\Dto\ResetPasswordRequest` object instead a `User` because we specified it as `input` and set `messenger=input`:
+
+```php
+<?php
+
+// api/src/Handler/ResetPasswordRequestHandler.php
+
+namespace App\Handler;
+
+use App\Dto\ResetPasswordRequest;
+use Symfony\Component\Messenger\Handler\MessageHandlerInterface;
+
+final class ResetPasswordRequestHandler implements MessageHandlerInterface
+{
+    public function __invoke(ResetPasswordRequest $forgotPassword)
+    {
+        // do something with the resource
+    }
+}
+```