Skip to content

Commit 14392c4

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '5.4' into 6.0
* 5.4: Minor tweaks [Notifier] Notifier docs merge
2 parents 3f609ff + a671edf commit 14392c4

File tree

9 files changed

+566
-545
lines changed

9 files changed

+566
-545
lines changed

‎_build/redirection_map

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -541,6 +541,9 @@
541541
/components/yaml/yaml_format /components/yaml#yaml-format
542542
/components/expression_language/syntax /components/expression_language#expression-language-syntax
543543
/components/expression_language/extending /components/expression_language#expression-language-extending
544+
/notifier/chatters /notifier#sending-chat-messages
545+
/notifier/texters /notifier#sending-sms
546+
/notifier/events /notifier#notifier-events
544547
/email /mailer
545548
/frontend/assetic /frontend
546549
/frontend/assetic/index /frontend

‎notifier.rst

Lines changed: 165 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,6 @@ The notifier component supports the following channels:
4242
API's tokens.
4343

4444
.. _notifier-sms-channel:
45-
.. _notifier-texter-dsn:
4645

4746
SMS Channel
4847
~~~~~~~~~~~
@@ -143,8 +142,41 @@ configure the ``texter_transports``:
143142
;
144143
};
145144
145+
.. _sending-sms:
146+
147+
The :class:`Symfony\\Component\\Notifier\\TexterInterface` class allows you to
148+
send SMS messages::
149+
150+
// src/Controller/SecurityController.php
151+
namespace App\Controller;
152+
153+
use Symfony\Component\Notifier\Message\SmsMessage;
154+
use Symfony\Component\Notifier\TexterInterface;
155+
use Symfony\Component\Routing\Annotation\Route;
156+
157+
class SecurityController
158+
{
159+
#[Route('/login/success')]
160+
public function loginSuccess(TexterInterface $texter)
161+
{
162+
$sms = new SmsMessage(
163+
// the phone number to send the SMS message to
164+
'+1411111111',
165+
// the message
166+
'A new login was detected!'
167+
);
168+
169+
$sentMessage = $texter->send($sms);
170+
171+
// ...
172+
}
173+
}
174+
175+
The ``send()`` method returns a variable of type
176+
:class:`Symfony\\Component\\Notifier\\Message\\SentMessage` which provides
177+
information such as the message ID and the original message contents.
178+
146179
.. _notifier-chat-channel:
147-
.. _notifier-chatter-dsn:
148180

149181
Chat Channel
150182
~~~~~~~~~~~~
@@ -160,24 +192,24 @@ The chat channel is used to send chat messages to users by using
160192
:class:`Symfony\\Component\\Notifier\\Chatter` classes. Symfony provides
161193
integration with these chat services:
162194

163-
============== ==================================== =============================================================================
164-
Service Package DSN
165-
============== ==================================== =============================================================================
166-
AmazonSns ``symfony/amazon-sns-notifier`` ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION``
167-
Discord ``symfony/discord-notifier`` ``discord://TOKEN@default?webhook_id=ID``
168-
FakeChat ``symfony/fake-chat-notifier`` ``fakechat+email://default?to=TO&from=FROM`` or ``fakechat+logger://default``
169-
Firebase ``symfony/firebase-notifier`` ``firebase://USERNAME:PASSWORD@default``
170-
Gitter ``symfony/gitter-notifier`` ``gitter://TOKEN@default?room_id=ROOM_ID``
171-
GoogleChat ``symfony/google-chat-notifier`` ``googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?thread_key=THREAD_KEY``
172-
LinkedIn ``symfony/linked-in-notifier`` ``linkedin://TOKEN:USER_ID@default``
173-
Mattermost ``symfony/mattermost-notifier`` ``mattermost://ACCESS_TOKEN@HOST/PATH?channel=CHANNEL``
174-
Mercure ``symfony/mercure-notifier`` ``mercure://HUB_ID?topic=TOPIC``
175-
MicrosoftTeams ``symfony/microsoft-teams-notifier`` ``microsoftteams://default/PATH``
176-
RocketChat ``symfony/rocket-chat-notifier`` ``rocketchat://TOKEN@ENDPOINT?channel=CHANNEL``
177-
Slack ``symfony/slack-notifier`` ``slack://TOKEN@default?channel=CHANNEL``
178-
Telegram ``symfony/telegram-notifier`` ``telegram://TOKEN@default?channel=CHAT_ID``
179-
Zulip ``symfony/zulip-notifier`` ``zulip://EMAIL:TOKEN@HOST?channel=CHANNEL``
180-
============== ==================================== =============================================================================
195+
====================================== ==================================== =============================================================================
196+
Service Package DSN
197+
====================================== ==================================== =============================================================================
198+
AmazonSns ``symfony/amazon-sns-notifier`` ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION``
199+
:doc:`Discord <notifier/discord>` ``symfony/discord-notifier`` ``discord://TOKEN@default?webhook_id=ID``
200+
FakeChat ``symfony/fake-chat-notifier`` ``fakechat+email://default?to=TO&from=FROM`` or ``fakechat+logger://default``
201+
Firebase ``symfony/firebase-notifier`` ``firebase://USERNAME:PASSWORD@default``
202+
Gitter ``symfony/gitter-notifier`` ``gitter://TOKEN@default?room_id=ROOM_ID``
203+
GoogleChat ``symfony/google-chat-notifier`` ``googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?thread_key=THREAD_KEY``
204+
LinkedIn ``symfony/linked-in-notifier`` ``linkedin://TOKEN:USER_ID@default``
205+
Mattermost ``symfony/mattermost-notifier`` ``mattermost://ACCESS_TOKEN@HOST/PATH?channel=CHANNEL``
206+
Mercure ``symfony/mercure-notifier`` ``mercure://HUB_ID?topic=TOPIC``
207+
:doc:`MicrosoftTeams <notifier/teams>` ``symfony/microsoft-teams-notifier`` ``microsoftteams://default/PATH``
208+
RocketChat ``symfony/rocket-chat-notifier`` ``rocketchat://TOKEN@ENDPOINT?channel=CHANNEL``
209+
:doc:`Slack <notifier/slack>` ``symfony/slack-notifier`` ``slack://TOKEN@default?channel=CHANNEL``
210+
:doc:`Telegram <notifier/telegram>` ``symfony/telegram-notifier`` ``telegram://TOKEN@default?channel=CHAT_ID``
211+
Zulip ``symfony/zulip-notifier`` ``zulip://EMAIL:TOKEN@HOST?channel=CHANNEL``
212+
====================================== ==================================== =============================================================================
181213

182214
Chatters are configured using the ``chatter_transports`` setting:
183215

@@ -228,6 +260,41 @@ Chatters are configured using the ``chatter_transports`` setting:
228260
;
229261
};
230262
263+
.. _sending-chat-messages:
264+
265+
The :class:`Symfony\\Component\\Notifier\\ChatterInterface` class allows
266+
you to send messages to chat services::
267+
268+
// src/Controller/CheckoutController.php
269+
namespace App\Controller;
270+
271+
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
272+
use Symfony\Component\Notifier\ChatterInterface;
273+
use Symfony\Component\Notifier\Message\ChatMessage;
274+
use Symfony\Component\Routing\Annotation\Route;
275+
276+
class CheckoutController extends AbstractController
277+
{
278+
/**
279+
* @Route("/checkout/thankyou")
280+
*/
281+
public function thankyou(ChatterInterface $chatter)
282+
{
283+
$message = (new ChatMessage('You got a new invoice for 15 EUR.'))
284+
// if not set explicitly, the message is send to the
285+
// default transport (the first one configured)
286+
->transport('slack');
287+
288+
$sentMessage = $chatter->send($message);
289+
290+
// ...
291+
}
292+
}
293+
294+
The ``send()`` method returns a variable of type
295+
:class:`Symfony\\Component\\Notifier\\Message\\SentMessage` which provides
296+
information such as the message ID and the original message contents.
297+
231298
.. _notifier-email-channel:
232299

233300
Email Channel
@@ -696,18 +763,87 @@ all configured texter and chatter transports only in the ``dev`` (and/or
696763
chatter_transports:
697764
slack: 'null://null'
698765
766+
.. _notifier-events:
767+
768+
.. index::
769+
single: Notifier; Events
770+
771+
Using Events
772+
------------
773+
774+
The :class:`Symfony\\Component\\Notifier\\Transport`` class of the Notifier component
775+
allows you to optionally hook into the lifecycle via events.
776+
777+
The ``MessageEvent::class`` Event
778+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
779+
780+
**Typical Purposes**: Doing something before the message is send (like logging
781+
which message is going to be send, or displaying something about the event
782+
to be executed.
783+
784+
Just before send the message, the event class ``MessageEvent`` is
785+
dispatched. Listeners receive a
786+
:class:`Symfony\\Component\\Notifier\\Event\\MessageEvent` event::
787+
788+
use Symfony\Component\Notifier\Event\MessageEvent;
789+
790+
$dispatcher->addListener(MessageEvent::class, function (MessageEvent $event) {
791+
// gets the message instance
792+
$message = $event->getMessage();
793+
794+
// log something
795+
$this->logger(sprintf('Message with subject: %s will be send to %s, $message->getSubject(), $message->getRecipientId()'));
796+
});
797+
798+
The ``FailedMessageEvent`` Event
799+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
800+
801+
**Typical Purposes**: Doing something before the exception is thrown
802+
(Retry to send the message or log additional information).
803+
804+
Whenever an exception is thrown while sending the message, the event class
805+
``FailedMessageEvent`` is dispatched. A listener can do anything useful before
806+
the exception is thrown.
807+
808+
Listeners receive a
809+
:class:`Symfony\\Component\\Notifier\\Event\\FailedMessageEvent` event::
810+
811+
use Symfony\Component\Notifier\Event\FailedMessageEvent;
812+
813+
$dispatcher->addListener(FailedMessageEvent::class, function (FailedMessageEvent $event) {
814+
// gets the message instance
815+
$message = $event->getMessage();
816+
817+
// gets the error instance
818+
$error = $event->getError();
819+
820+
// log something
821+
$this->logger(sprintf('The message with subject: %s has not been sent successfully. The error is: %s, $message->getSubject(), $error->getMessage()'));
822+
});
823+
824+
The ``SentMessageEvent`` Event
825+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
826+
827+
**Typical Purposes**: To perform some action when the message is successfully
828+
sent (like retrieve the id returned when the message is sent).
829+
830+
After the message has been successfully sent, the event class ``SentMessageEvent``
831+
is dispatched. Listeners receive a
832+
:class:`Symfony\\Component\\Notifier\\Event\\SentMessageEvent` event::
833+
834+
use Symfony\Component\Notifier\Event\SentMessageEvent;
835+
836+
$dispatcher->addListener(SentMessageEvent::class, function (SentMessageEvent $event) {
837+
// gets the message instance
838+
$message = $event->getOriginalMessage();
839+
840+
// log something
841+
$this->logger(sprintf('The message has been successfully sent and have id: %s, $message->getMessageId()'));
842+
});
843+
699844
.. TODO
700845
.. - Using the message bus for asynchronous notification
701846
.. - Describe notifier monolog handler
702847
.. - Describe notification_on_failed_messages integration
703848
704-
Learn more
705-
----------
706-
707-
.. toctree::
708-
:maxdepth: 1
709-
:glob:
710-
711-
notifier/*
712-
713849
.. _`RFC 3986`: https://www.ietf.org/rfc/rfc3986.txt

0 commit comments

Comments
 (0)