Skip to content

Commit cdab03a

Browse files
committed
feature #15597 [Notifier] Add Documentation for Events (ismail1432)
This PR was merged into the 5.4 branch. Discussion ---------- [Notifier] Add Documentation for Events I would like to add documentation for the events available in the Notifier, see #15589 I don't know if I have the good approach (create a specific page like for [console events](https://symfony.com/doc/current/components/console/events.html)) Commits ------- 98270d1 init doc
2 parents 01e323f + 98270d1 commit cdab03a

File tree

1 file changed

+74
-0
lines changed

1 file changed

+74
-0
lines changed

notifier/events.rst

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
.. index::
2+
single: Notifier; Events
3+
4+
Using Events
5+
============
6+
7+
The class:``...\\..\\Transport`` of the Notifier component allows you to optionally hook
8+
into the lifecycle via events.
9+
10+
The ``MessageEvent::class`` Event
11+
---------------------------------
12+
13+
**Typical Purposes**: Doing something before the message is send (like logging
14+
which message is going to be send, or displaying something about the event
15+
to be executed.
16+
17+
Just before send the message, the event class ``MessageEvent`` is
18+
dispatched. Listeners receive a
19+
:class:`Symfony\\Component\\Notifier\\Event\\MessageEvent` event::
20+
21+
use Symfony\Component\Notifier\Event\MessageEvent;
22+
23+
$dispatcher->addListener(MessageEvent::class, function (MessageEvent $event) {
24+
// gets the message instance
25+
$message = $event->getMessage();
26+
27+
// log something
28+
$this->logger(sprintf('Message with subject: %s will be send to %s, $message->getSubject(), $message->getRecipientId()'));
29+
});
30+
31+
The ``FailedMessageEvent`` Event
32+
--------------------------------
33+
34+
**Typical Purposes**: Doing something before the exception is thrown (Retry to send the message or log additional information).
35+
36+
Whenever an exception is thrown while sending the message, the event class ``FailedMessageEvent`` is
37+
dispatched. A listener can do anything useful before the exception is thrown.
38+
39+
Listeners receive a
40+
:class:`Symfony\\Component\\Notifier\\Event\\FailedMessageEvent` event::
41+
42+
use Symfony\Component\Notifier\Event\FailedMessageEvent;
43+
44+
$dispatcher->addListener(FailedMessageEvent::class, function (FailedMessageEvent $event) {
45+
// gets the message instance
46+
$message = $event->getMessage();
47+
48+
// gets the error instance
49+
$error = $event->getError();
50+
51+
// log something
52+
$this->logger(sprintf('The message with subject: %s has not been sent successfully. The error is: %s, $message->getSubject(), $error->getMessage()'));
53+
});
54+
55+
56+
The ``SentMessageEvent`` Event
57+
------------------------------
58+
59+
**Typical Purposes**: To perform some action when the message is successfully sent (like retrieve the id returned
60+
when the message is sent).
61+
62+
After the message has been successfully sent, the event class ``SentMessageEvent`` is
63+
dispatched. Listeners receive a
64+
:class:`Symfony\\Component\\Notifier\\Event\\SentMessageEvent` event::
65+
66+
use Symfony\Component\Notifier\Event\SentMessageEvent;
67+
68+
$dispatcher->addListener(SentMessageEvent::class, function (SentMessageEvent $event) {
69+
// gets the message instance
70+
$message = $event->getOriginalMessage();
71+
72+
// log something
73+
$this->logger(sprintf('The message has been successfully sent and have id: %s, $message->getMessageId()'));
74+
});

0 commit comments

Comments
 (0)