Skip to content

[doc][skip ci] Add processor examples, notes on exception and more. #283

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 1, 2017
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 44 additions & 4 deletions docs/consumption/message_processor.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
# Message processor

* [Basics](#basics)
* [Reply result](#reply-result)
* [On exceptions](#on-exceptions)
* [Examples](#examples)


## Basics

The message processor is an object that actually process the message and must return a result status.
Here's example:

Expand All @@ -20,9 +28,15 @@ class SendMailProcessor implements PsrProcessor
}
```

Usually there is no need to catch exceptions.
The message broker can detect consumer has failed and redeliver the message.
Sometimes you have to reject messages explicitly.
By returning `self::ACK` a processor tells a broker that the message has been processed correctly.

There are other statuses:

* `self::ACK` - Use this constant when the message is processed successfully and the message could be removed from the queue.
* `self::REJECT` - Use this constant when the message is not valid or could not be processed. The message is removed from the queue.
* `self::REQUEUE` - Use this constant when the message is not valid or could not be processed right now but we can try again later

Look at the next example that shows the message validation before sending a mail. If the message is not valid a processor rejects it.

```php
<?php
Expand Down Expand Up @@ -95,7 +109,11 @@ class SendMailProcessor implements PsrProcessor
}
```

The consumption component provide some useful extensions, for example there is an extension that makes RPC processing simplier.
## Reply result

The consumption component provide some useful extensions, for example there is an extension that makes RPC processing simpler.
The producer might wait for a reply from a consumer and in order to send it a processor has to return a reply result.
Dont forget to add `ReplyExtension`.

```php
<?php
Expand Down Expand Up @@ -130,4 +148,26 @@ $queueConsumer->bind('foo', new SendMailProcessor());
$queueConsumer->consume();
```


## On exceptions

It is advised to not catch exceptions and [fail fast](https://en.wikipedia.org/wiki/Fail-fast).
Also consider using [supervisord](supervisord.org) or similar process manager to restart exited consumers.

Despite advising to fail there are some cases where you might want to catch exceptions.

* A message validator throws an exception on invalid message. It is better to catch it and return `REJECT`.
* Some transports ([Doctrine DBAL](../transport/dbal.md), [Filesystem](../transport/filesystem.md), [Redis](../transport/redis.md)) does notice an error,
and therefor won't be able to redeliver the message. The message is completely lost. You might want to catch an exception to properly redelivery\requeue the message.

# Examples

Feel free to contribute your own.

* [LiipImagineBundle. ResolveCacheProcessor](https://github.com/liip/LiipImagineBundle/blob/713e36f5df353d7c5345daed5a2eefc23c103849/Async/ResolveCacheProcessor.php#L1)
* [EnqueueElasticaBundle. ElasticaPopulateProcessor](https://github.com/php-enqueue/enqueue-elastica-bundle/blob/7c05c55b1667f9cae98325257ba24fc101f87f97/Async/ElasticaPopulateProcessor.php#L1)
* [formapro/pvm. HandleAsyncTransitionProcessor](https://github.com/formapro/pvm/blob/d5e989a77eb1540a93e69abacc446b3d7937292d/src/Enqueue/HandleAsyncTransitionProcessor.php#L1)
* [php-quartz. EnqueueRemoteTransportProcessor](https://github.com/php-quartz/quartz-dev/blob/91690aa535b0322510b4555dab59d6ae9d7044e5/pkg/bridge/Enqueue/EnqueueRemoteTransportProcessor.php#L1)
* [php-comrade. CreateJobProcessor](https://github.com/php-comrade/comrade-dev/blob/43c0662b74340aae318bceb15d8564670325dcee/apps/jm/src/Queue/CreateJobProcessor.php#L1)

[back to index](../index.md)