# Symfony Messenger Integration: CQRS and Async Message Processing

API Platform provides an integration with the [Symfony Messenger Component](https://symfony.com/doc/current/messenger.html).

This feature allows to implement the [Command Query Responsibility Segregation (CQRS)](https://martinfowler.com/bliki/CQRS.html) pattern in a convenient way.
It also makes it easy to send messages through the web API that will be consumed asynchronously.

Many transports are supported to dispatch messages to async consumers, including RabbitMQ, Apache Kafka, Amazon SQS and Google Pub/Sub.

## Installing Symfony Messenger

To enable the support of Messenger, install the library:

```console
composer require symfony/messenger
```

## Dispatching a Resource through the Message Bus

Set the `messenger` attribute to `true`, and API Platform will automatically dispatch the API Resource instance as a message using the message bus provided by the Messenger Component. The following example allows you to create a new `Person` in an asynchronous manner:

<code-selector>

```php
<?php
// api/src/Entity/Person.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ApiProperty;
use ApiPlatform\Metadata\Post;
use Symfony\Component\Validator\Constraints as Assert;

#[ApiResource(operations: [
  new Post(messenger: true, output: false, status: 202)
])]
final class Person
{
    #[ApiProperty(identifier: true)]
    public string $id;

    #[Assert\NotBlank]
    public string $name;
}
```

```yaml
# api/config/api_platform/resources.yaml
resources:
  App\Entity\Person:
    operations:
      ApiPlatform\Metadata\Post:
        status: 202
        messenger: true
        output: false
```

</code-selector>

Because the `messenger` attribute is `true`, when a `POST` is handled by API Platform, the corresponding instance of the `Person` will be dispatched.

For this example, only the `POST` operation is enabled. If the resource does not have any `Get` operation, API Platform [automatically adds an operation to help generating an IRI identify the resource](../core/operations/#enabling-and-disabling-operations).
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](../core/serialization.md) will be skipped.

**Note:** when using `messenger=true` ApiResource attribute in a Doctrine entity, the Doctrine Processor is not called. If you want the Doctrine Processor to be called, you should [decorate a built-in state processor](../core/state-processors.md#creating-a-custom-state-processor) and implement your own logic.

## Registering a Message Handler

To process the message that will be dispatched, [a handler](https://symfony.com/doc/current/messenger.html#registering-handlers) must be created:

```php
<?php
// api/src/Handler/PersonHandler.php

namespace App\Handler;

use App\Entity\Person;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler]
final class PersonHandler
{
    public function __invoke(Person $person)
    {
        // do something with the resource
    }
}
```

That's all!

By default, the handler will process your message synchronously.
If you want it to be consumed asynchronously (e.g. by a worker machine), [configure a transport and the consumer](https://symfony.com/doc/current/messenger.html#transports).

## Accessing the Data Returned by the Handler

API Platform automatically uses the `Symfony\Component\Messenger\Stamp\HandledStamp` when set.
It means that if you use a synchronous handler, the data returned by the `__invoke` method replaces the original data.

In cases where multiple handlers are registered, the last handler return value will be used as output. If none are returned, ensure resource configuration defines no output with `output=false`.
Handler ordering can be configured [using messenger priority tag](https://symfony.com/doc/current/messenger.html#manually-configuring-handlers).

## Detecting Removals

When a `DELETE` operation occurs, API Platform automatically adds a `ApiPlatform\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](../core/dto.md)) that handles the given `input`. In this example, we'll handle a `ResetPasswordRequest` on a custom operation on our `User` resource:

```php
<?php
// api/src/Entity/User.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;
use App\Dto\ResetPasswordRequest;

#[ApiResource(operations: [
  new GetCollection(),
  new Post(),
  new Post(
      name: 'reset_password',
      status: 202,
      messenger: 'input',
      input: ResetPasswordRequest::class,
      output: false,
      uriTemplate: '/users/reset_password'
  )
])]
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
{
    public string $username;
}
```

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](../core/serialization.md) will be skipped.

In this case, when a `POST` request is issued on `/users/reset_password` the message handler will receive an `App\Dto\ResetPasswordRequest` object instead of 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\Attribute\AsMessageHandler;

#[AsMessageHandler]
final class ResetPasswordRequestHandler
{
    public function __invoke(ResetPasswordRequest $forgotPassword)
    {
        // do something with the resource
    }
}
```