Skip to content

Commit 0a704b3

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '6.1' into 6.2
* 6.1: Minor tweaks [Notifier] Notifier docs merge
2 parents 76a0dbd + 6ae741f commit 0a704b3

File tree

9 files changed

+600
-579
lines changed

9 files changed

+600
-579
lines changed

‎_build/redirection_map

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

‎notifier.rst

Lines changed: 173 additions & 31 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
~~~~~~~~~~~
@@ -159,8 +158,47 @@ configure the ``texter_transports``:
159158
;
160159
};
161160
161+
.. _sending-sms:
162+
163+
The :class:`Symfony\\Component\\Notifier\\TexterInterface` class allows you to
164+
send SMS messages::
165+
166+
// src/Controller/SecurityController.php
167+
namespace App\Controller;
168+
169+
use Symfony\Component\Notifier\Message\SmsMessage;
170+
use Symfony\Component\Notifier\TexterInterface;
171+
use Symfony\Component\Routing\Annotation\Route;
172+
173+
class SecurityController
174+
{
175+
#[Route('/login/success')]
176+
public function loginSuccess(TexterInterface $texter)
177+
{
178+
$sms = new SmsMessage(
179+
// the phone number to send the SMS message to
180+
'+1411111111',
181+
// the message
182+
'A new login was detected!',
183+
// optionally, you can override default "from" defined in transports
184+
'+1422222222',
185+
);
186+
187+
$sentMessage = $texter->send($sms);
188+
189+
// ...
190+
}
191+
}
192+
193+
.. versionadded:: 6.2
194+
195+
The 3rd argument of ``SmsMessage`` (``$from``) was introduced in Symfony 6.2.
196+
197+
The ``send()`` method returns a variable of type
198+
:class:`Symfony\\Component\\Notifier\\Message\\SentMessage` which provides
199+
information such as the message ID and the original message contents.
200+
162201
.. _notifier-chat-channel:
163-
.. _notifier-chatter-dsn:
164202

165203
Chat Channel
166204
~~~~~~~~~~~~
@@ -176,26 +214,26 @@ The chat channel is used to send chat messages to users by using
176214
:class:`Symfony\\Component\\Notifier\\Chatter` classes. Symfony provides
177215
integration with these chat services:
178216

179-
============== ==================================== =============================================================================
180-
Service Package DSN
181-
============== ==================================== =============================================================================
182-
AmazonSns ``symfony/amazon-sns-notifier`` ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION``
183-
Chatwork ``symfony/chatwork-notifier`` ``chatwork://API_TOKEN@default?room_id=ID``
184-
Discord ``symfony/discord-notifier`` ``discord://TOKEN@default?webhook_id=ID``
185-
FakeChat ``symfony/fake-chat-notifier`` ``fakechat+email://default?to=TO&from=FROM`` or ``fakechat+logger://default``
186-
Firebase ``symfony/firebase-notifier`` ``firebase://USERNAME:PASSWORD@default``
187-
Gitter ``symfony/gitter-notifier`` ``gitter://TOKEN@default?room_id=ROOM_ID``
188-
GoogleChat ``symfony/google-chat-notifier`` ``googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?thread_key=THREAD_KEY``
189-
LinkedIn ``symfony/linked-in-notifier`` ``linkedin://TOKEN:USER_ID@default``
190-
Mattermost ``symfony/mattermost-notifier`` ``mattermost://ACCESS_TOKEN@HOST/PATH?channel=CHANNEL``
191-
Mercure ``symfony/mercure-notifier`` ``mercure://HUB_ID?topic=TOPIC``
192-
MicrosoftTeams ``symfony/microsoft-teams-notifier`` ``microsoftteams://default/PATH``
193-
RocketChat ``symfony/rocket-chat-notifier`` ``rocketchat://TOKEN@ENDPOINT?channel=CHANNEL``
194-
Slack ``symfony/slack-notifier`` ``slack://TOKEN@default?channel=CHANNEL``
195-
Telegram ``symfony/telegram-notifier`` ``telegram://TOKEN@default?channel=CHAT_ID``
196-
Zendesk ``symfony/zendesk-notifier`` ``zendesk://EMAIL:TOKEN@SUBDOMAIN``
197-
Zulip ``symfony/zulip-notifier`` ``zulip://EMAIL:TOKEN@HOST?channel=CHANNEL``
198-
============== ==================================== =============================================================================
217+
====================================== ==================================== =============================================================================
218+
Service Package DSN
219+
====================================== ==================================== =============================================================================
220+
AmazonSns ``symfony/amazon-sns-notifier`` ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION``
221+
Chatwork ``symfony/chatwork-notifier`` ``chatwork://API_TOKEN@default?room_id=ID``
222+
:doc:`Discord <notifier/discord>` ``symfony/discord-notifier`` ``discord://TOKEN@default?webhook_id=ID``
223+
FakeChat ``symfony/fake-chat-notifier`` ``fakechat+email://default?to=TO&from=FROM`` or ``fakechat+logger://default``
224+
Firebase ``symfony/firebase-notifier`` ``firebase://USERNAME:PASSWORD@default``
225+
Gitter ``symfony/gitter-notifier`` ``gitter://TOKEN@default?room_id=ROOM_ID``
226+
GoogleChat ``symfony/google-chat-notifier`` ``googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?thread_key=THREAD_KEY``
227+
LinkedIn ``symfony/linked-in-notifier`` ``linkedin://TOKEN:USER_ID@default``
228+
Mattermost ``symfony/mattermost-notifier`` ``mattermost://ACCESS_TOKEN@HOST/PATH?channel=CHANNEL``
229+
Mercure ``symfony/mercure-notifier`` ``mercure://HUB_ID?topic=TOPIC``
230+
:doc:`MicrosoftTeams <notifier/teams>` ``symfony/microsoft-teams-notifier`` ``microsoftteams://default/PATH``
231+
RocketChat ``symfony/rocket-chat-notifier`` ``rocketchat://TOKEN@ENDPOINT?channel=CHANNEL``
232+
:doc:`Slack <notifier/slack>` ``symfony/slack-notifier`` ``slack://TOKEN@default?channel=CHANNEL``
233+
:doc:`Telegram <notifier/telegram>` ``symfony/telegram-notifier`` ``telegram://TOKEN@default?channel=CHAT_ID``
234+
Zendesk ``symfony/zendesk-notifier`` ``zendesk://EMAIL:TOKEN@SUBDOMAIN``
235+
Zulip ``symfony/zulip-notifier`` ``zulip://EMAIL:TOKEN@HOST?channel=CHANNEL``
236+
====================================== ==================================== =============================================================================
199237

200238
.. versionadded:: 6.2
201239

@@ -250,6 +288,41 @@ Chatters are configured using the ``chatter_transports`` setting:
250288
;
251289
};
252290
291+
.. _sending-chat-messages:
292+
293+
The :class:`Symfony\\Component\\Notifier\\ChatterInterface` class allows
294+
you to send messages to chat services::
295+
296+
// src/Controller/CheckoutController.php
297+
namespace App\Controller;
298+
299+
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
300+
use Symfony\Component\Notifier\ChatterInterface;
301+
use Symfony\Component\Notifier\Message\ChatMessage;
302+
use Symfony\Component\Routing\Annotation\Route;
303+
304+
class CheckoutController extends AbstractController
305+
{
306+
/**
307+
* @Route("/checkout/thankyou")
308+
*/
309+
public function thankyou(ChatterInterface $chatter)
310+
{
311+
$message = (new ChatMessage('You got a new invoice for 15 EUR.'))
312+
// if not set explicitly, the message is send to the
313+
// default transport (the first one configured)
314+
->transport('slack');
315+
316+
$sentMessage = $chatter->send($message);
317+
318+
// ...
319+
}
320+
}
321+
322+
The ``send()`` method returns a variable of type
323+
:class:`Symfony\\Component\\Notifier\\Message\\SentMessage` which provides
324+
information such as the message ID and the original message contents.
325+
253326
.. _notifier-email-channel:
254327

255328
Email Channel
@@ -794,18 +867,87 @@ all configured texter and chatter transports only in the ``dev`` (and/or
794867
chatter_transports:
795868
slack: 'null://null'
796869
870+
.. _notifier-events:
871+
872+
.. index::
873+
single: Notifier; Events
874+
875+
Using Events
876+
------------
877+
878+
The :class:`Symfony\\Component\\Notifier\\Transport`` class of the Notifier component
879+
allows you to optionally hook into the lifecycle via events.
880+
881+
The ``MessageEvent::class`` Event
882+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
883+
884+
**Typical Purposes**: Doing something before the message is send (like logging
885+
which message is going to be send, or displaying something about the event
886+
to be executed.
887+
888+
Just before send the message, the event class ``MessageEvent`` is
889+
dispatched. Listeners receive a
890+
:class:`Symfony\\Component\\Notifier\\Event\\MessageEvent` event::
891+
892+
use Symfony\Component\Notifier\Event\MessageEvent;
893+
894+
$dispatcher->addListener(MessageEvent::class, function (MessageEvent $event) {
895+
// gets the message instance
896+
$message = $event->getMessage();
897+
898+
// log something
899+
$this->logger(sprintf('Message with subject: %s will be send to %s, $message->getSubject(), $message->getRecipientId()'));
900+
});
901+
902+
The ``FailedMessageEvent`` Event
903+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
904+
905+
**Typical Purposes**: Doing something before the exception is thrown
906+
(Retry to send the message or log additional information).
907+
908+
Whenever an exception is thrown while sending the message, the event class
909+
``FailedMessageEvent`` is dispatched. A listener can do anything useful before
910+
the exception is thrown.
911+
912+
Listeners receive a
913+
:class:`Symfony\\Component\\Notifier\\Event\\FailedMessageEvent` event::
914+
915+
use Symfony\Component\Notifier\Event\FailedMessageEvent;
916+
917+
$dispatcher->addListener(FailedMessageEvent::class, function (FailedMessageEvent $event) {
918+
// gets the message instance
919+
$message = $event->getMessage();
920+
921+
// gets the error instance
922+
$error = $event->getError();
923+
924+
// log something
925+
$this->logger(sprintf('The message with subject: %s has not been sent successfully. The error is: %s, $message->getSubject(), $error->getMessage()'));
926+
});
927+
928+
The ``SentMessageEvent`` Event
929+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
930+
931+
**Typical Purposes**: To perform some action when the message is successfully
932+
sent (like retrieve the id returned when the message is sent).
933+
934+
After the message has been successfully sent, the event class ``SentMessageEvent``
935+
is dispatched. Listeners receive a
936+
:class:`Symfony\\Component\\Notifier\\Event\\SentMessageEvent` event::
937+
938+
use Symfony\Component\Notifier\Event\SentMessageEvent;
939+
940+
$dispatcher->addListener(SentMessageEvent::class, function (SentMessageEvent $event) {
941+
// gets the message instance
942+
$message = $event->getOriginalMessage();
943+
944+
// log something
945+
$this->logger(sprintf('The message has been successfully sent and have id: %s, $message->getMessageId()'));
946+
});
947+
797948
.. TODO
798949
.. - Using the message bus for asynchronous notification
799950
.. - Describe notifier monolog handler
800951
.. - Describe notification_on_failed_messages integration
801952
802-
Learn more
803-
----------
804-
805-
.. toctree::
806-
:maxdepth: 1
807-
:glob:
808-
809-
notifier/*
810-
811953
.. _`RFC 3986`: https://www.ietf.org/rfc/rfc3986.txt

0 commit comments

Comments
 (0)