Skip to content

Commit 26a2439

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '6.2' into 6.3
* 6.2: Minor tweaks [Notifier] Notifier docs merge
2 parents 43cce80 + 0a704b3 commit 26a2439

File tree

8 files changed

+625
-156
lines changed

8 files changed

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

175213
Chat Channel
176214
~~~~~~~~~~~~
@@ -186,29 +224,29 @@ The chat channel is used to send chat messages to users by using
186224
:class:`Symfony\\Component\\Notifier\\Chatter` classes. Symfony provides
187225
integration with these chat services:
188226

189-
============== ==================================== ===============================================================================
190-
Service Package DSN
191-
============== ==================================== ===============================================================================
192-
AmazonSns ``symfony/amazon-sns-notifier`` ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION``
193-
Chatwork ``symfony/chatwork-notifier`` ``chatwork://API_TOKEN@default?room_id=ID``
194-
Discord ``symfony/discord-notifier`` ``discord://TOKEN@default?webhook_id=ID``
195-
FakeChat ``symfony/fake-chat-notifier`` ``fakechat+email://default?to=TO&from=FROM`` or ``fakechat+logger://default``
196-
Firebase ``symfony/firebase-notifier`` ``firebase://USERNAME:PASSWORD@default``
197-
Gitter ``symfony/gitter-notifier`` ``gitter://TOKEN@default?room_id=ROOM_ID``
198-
GoogleChat ``symfony/google-chat-notifier`` ``googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?thread_key=THREAD_KEY``
199-
LINE Notify ``symfony/line-notify-notifier`` ``linenotify://TOKEN@default``
200-
LinkedIn ``symfony/linked-in-notifier`` ``linkedin://TOKEN:USER_ID@default``
201-
Mastodon ``symfony/mastodon-notifier`` ``mastodon://ACCESS_TOKEN@HOST``
202-
Mattermost ``symfony/mattermost-notifier`` ``mattermost://ACCESS_TOKEN@HOST/PATH?channel=CHANNEL``
203-
Mercure ``symfony/mercure-notifier`` ``mercure://HUB_ID?topic=TOPIC``
204-
MicrosoftTeams ``symfony/microsoft-teams-notifier`` ``microsoftteams://default/PATH``
205-
RocketChat ``symfony/rocket-chat-notifier`` ``rocketchat://TOKEN@ENDPOINT?channel=CHANNEL``
206-
Slack ``symfony/slack-notifier`` ``slack://TOKEN@default?channel=CHANNEL``
207-
Telegram ``symfony/telegram-notifier`` ``telegram://TOKEN@default?channel=CHAT_ID``
208-
Twitter ``symfony/twitter-notifier`` ``twitter://API_KEY:API_SECRET:ACCESS_TOKEN:ACCESS_SECRET@default``
209-
Zendesk ``symfony/zendesk-notifier`` ``zendesk://EMAIL:TOKEN@SUBDOMAIN``
210-
Zulip ``symfony/zulip-notifier`` ``zulip://EMAIL:TOKEN@HOST?channel=CHANNEL``
211-
============== ==================================== ===============================================================================
227+
====================================== ==================================== =============================================================================
228+
Service Package DSN
229+
====================================== ==================================== =============================================================================
230+
AmazonSns ``symfony/amazon-sns-notifier`` ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION``
231+
Chatwork ``symfony/chatwork-notifier`` ``chatwork://API_TOKEN@default?room_id=ID``
232+
:doc:`Discord <notifier/discord>` ``symfony/discord-notifier`` ``discord://TOKEN@default?webhook_id=ID``
233+
FakeChat ``symfony/fake-chat-notifier`` ``fakechat+email://default?to=TO&from=FROM`` or ``fakechat+logger://default``
234+
Firebase ``symfony/firebase-notifier`` ``firebase://USERNAME:PASSWORD@default``
235+
Gitter ``symfony/gitter-notifier`` ``gitter://TOKEN@default?room_id=ROOM_ID``
236+
GoogleChat ``symfony/google-chat-notifier`` ``googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?thread_key=THREAD_KEY``
237+
LINE Notify ``symfony/line-notify-notifier`` ``linenotify://TOKEN@default``
238+
LinkedIn ``symfony/linked-in-notifier`` ``linkedin://TOKEN:USER_ID@default``
239+
Mastodon ``symfony/mastodon-notifier`` ``mastodon://ACCESS_TOKEN@HOST``
240+
Mattermost ``symfony/mattermost-notifier`` ``mattermost://ACCESS_TOKEN@HOST/PATH?channel=CHANNEL``
241+
Mercure ``symfony/mercure-notifier`` ``mercure://HUB_ID?topic=TOPIC``
242+
:doc:`MicrosoftTeams <notifier/teams>` ``symfony/microsoft-teams-notifier`` ``microsoftteams://default/PATH``
243+
RocketChat ``symfony/rocket-chat-notifier`` ``rocketchat://TOKEN@ENDPOINT?channel=CHANNEL``
244+
:doc:`Slack <notifier/slack>` ``symfony/slack-notifier`` ``slack://TOKEN@default?channel=CHANNEL``
245+
:doc:`Telegram <notifier/telegram>` ``symfony/telegram-notifier`` ``telegram://TOKEN@default?channel=CHAT_ID``
246+
Twitter ``symfony/twitter-notifier`` ``twitter://API_KEY:API_SECRET:ACCESS_TOKEN:ACCESS_SECRET@default``
247+
Zendesk ``symfony/zendesk-notifier`` ``zendesk://EMAIL:TOKEN@SUBDOMAIN``
248+
Zulip ``symfony/zulip-notifier`` ``zulip://EMAIL:TOKEN@HOST?channel=CHANNEL``
249+
====================================== ==================================== =============================================================================
212250

213251
.. versionadded:: 6.2
214252

@@ -267,6 +305,41 @@ Chatters are configured using the ``chatter_transports`` setting:
267305
;
268306
};
269307
308+
.. _sending-chat-messages:
309+
310+
The :class:`Symfony\\Component\\Notifier\\ChatterInterface` class allows
311+
you to send messages to chat services::
312+
313+
// src/Controller/CheckoutController.php
314+
namespace App\Controller;
315+
316+
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
317+
use Symfony\Component\Notifier\ChatterInterface;
318+
use Symfony\Component\Notifier\Message\ChatMessage;
319+
use Symfony\Component\Routing\Annotation\Route;
320+
321+
class CheckoutController extends AbstractController
322+
{
323+
/**
324+
* @Route("/checkout/thankyou")
325+
*/
326+
public function thankyou(ChatterInterface $chatter)
327+
{
328+
$message = (new ChatMessage('You got a new invoice for 15 EUR.'))
329+
// if not set explicitly, the message is send to the
330+
// default transport (the first one configured)
331+
->transport('slack');
332+
333+
$sentMessage = $chatter->send($message);
334+
335+
// ...
336+
}
337+
}
338+
339+
The ``send()`` method returns a variable of type
340+
:class:`Symfony\\Component\\Notifier\\Message\\SentMessage` which provides
341+
information such as the message ID and the original message contents.
342+
270343
.. _notifier-email-channel:
271344

272345
Email Channel
@@ -816,18 +889,87 @@ all configured texter and chatter transports only in the ``dev`` (and/or
816889
chatter_transports:
817890
slack: 'null://null'
818891
892+
.. _notifier-events:
893+
894+
.. index::
895+
single: Notifier; Events
896+
897+
Using Events
898+
------------
899+
900+
The :class:`Symfony\\Component\\Notifier\\Transport`` class of the Notifier component
901+
allows you to optionally hook into the lifecycle via events.
902+
903+
The ``MessageEvent::class`` Event
904+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
905+
906+
**Typical Purposes**: Doing something before the message is send (like logging
907+
which message is going to be send, or displaying something about the event
908+
to be executed.
909+
910+
Just before send the message, the event class ``MessageEvent`` is
911+
dispatched. Listeners receive a
912+
:class:`Symfony\\Component\\Notifier\\Event\\MessageEvent` event::
913+
914+
use Symfony\Component\Notifier\Event\MessageEvent;
915+
916+
$dispatcher->addListener(MessageEvent::class, function (MessageEvent $event) {
917+
// gets the message instance
918+
$message = $event->getMessage();
919+
920+
// log something
921+
$this->logger(sprintf('Message with subject: %s will be send to %s, $message->getSubject(), $message->getRecipientId()'));
922+
});
923+
924+
The ``FailedMessageEvent`` Event
925+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
926+
927+
**Typical Purposes**: Doing something before the exception is thrown
928+
(Retry to send the message or log additional information).
929+
930+
Whenever an exception is thrown while sending the message, the event class
931+
``FailedMessageEvent`` is dispatched. A listener can do anything useful before
932+
the exception is thrown.
933+
934+
Listeners receive a
935+
:class:`Symfony\\Component\\Notifier\\Event\\FailedMessageEvent` event::
936+
937+
use Symfony\Component\Notifier\Event\FailedMessageEvent;
938+
939+
$dispatcher->addListener(FailedMessageEvent::class, function (FailedMessageEvent $event) {
940+
// gets the message instance
941+
$message = $event->getMessage();
942+
943+
// gets the error instance
944+
$error = $event->getError();
945+
946+
// log something
947+
$this->logger(sprintf('The message with subject: %s has not been sent successfully. The error is: %s, $message->getSubject(), $error->getMessage()'));
948+
});
949+
950+
The ``SentMessageEvent`` Event
951+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
952+
953+
**Typical Purposes**: To perform some action when the message is successfully
954+
sent (like retrieve the id returned when the message is sent).
955+
956+
After the message has been successfully sent, the event class ``SentMessageEvent``
957+
is dispatched. Listeners receive a
958+
:class:`Symfony\\Component\\Notifier\\Event\\SentMessageEvent` event::
959+
960+
use Symfony\Component\Notifier\Event\SentMessageEvent;
961+
962+
$dispatcher->addListener(SentMessageEvent::class, function (SentMessageEvent $event) {
963+
// gets the message instance
964+
$message = $event->getOriginalMessage();
965+
966+
// log something
967+
$this->logger(sprintf('The message has been successfully sent and have id: %s, $message->getMessageId()'));
968+
});
969+
819970
.. TODO
820971
.. - Using the message bus for asynchronous notification
821972
.. - Describe notifier monolog handler
822973
.. - Describe notification_on_failed_messages integration
823974
824-
Learn more
825-
----------
826-
827-
.. toctree::
828-
:maxdepth: 1
829-
:glob:
830-
831-
notifier/*
832-
833975
.. _`RFC 3986`: https://www.ietf.org/rfc/rfc3986.txt

‎notifier/discord.rst

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
.. index::
2+
single: Notifier; Chatters
3+
4+
Discord Notifier
5+
================
6+
7+
The Discord Notifier package allows to use Discord via the Symfony Notifier
8+
component. Read the :doc:`main Notifier docs </notifier>` to learn about installing
9+
and configuring that component.
10+
11+
Adding Interactions to a Message
12+
--------------------------------
13+
14+
With a Discord message, you can use the
15+
:class:`Symfony\\Component\\Notifier\\Bridge\\Discord\\DiscordOptions` class
16+
to add some interactive options called `Embed elements`_::
17+
18+
use Symfony\Component\Notifier\Bridge\Discord\DiscordOptions;
19+
use Symfony\Component\Notifier\Bridge\Discord\Embeds\DiscordEmbed;
20+
use Symfony\Component\Notifier\Bridge\Discord\Embeds\DiscordFieldEmbedObject;
21+
use Symfony\Component\Notifier\Bridge\Discord\Embeds\DiscordFooterEmbedObject;
22+
use Symfony\Component\Notifier\Bridge\Discord\Embeds\DiscordMediaEmbedObject;
23+
use Symfony\Component\Notifier\Message\ChatMessage;
24+
25+
$chatMessage = new ChatMessage('');
26+
27+
// Create Discord Embed
28+
$discordOptions = (new DiscordOptions())
29+
->username('connor bot')
30+
->addEmbed((new DiscordEmbed())
31+
->color(2021216)
32+
->title('New song added!')
33+
->thumbnail((new DiscordMediaEmbedObject())
34+
->url('https://i.scdn.co/image/ab67616d0000b2735eb27502aa5cb1b4c9db426b'))
35+
->addField((new DiscordFieldEmbedObject())
36+
->name('Track')
37+
->value('[Common Ground](https://open.spotify.com/track/36TYfGWUhIRlVjM8TxGUK6)')
38+
->inline(true)
39+
)
40+
->addField((new DiscordFieldEmbedObject())
41+
->name('Artist')
42+
->value('Alasdair Fraser')
43+
->inline(true)
44+
)
45+
->addField((new DiscordFieldEmbedObject())
46+
->name('Album')
47+
->value('Dawn Dance')
48+
->inline(true)
49+
)
50+
->footer((new DiscordFooterEmbedObject())
51+
->text('Added ...')
52+
->iconUrl('https://upload.wikimedia.org/wikipedia/commons/thumb/1/19/Spotify_logo_without_text.svg/200px-Spotify_logo_without_text.svg.png')
53+
)
54+
)
55+
;
56+
57+
// Add the custom options to the chat message and send the message
58+
$chatMessage->options($discordOptions);
59+
60+
$chatter->send($chatMessage);
61+
62+
.. _`Embed elements`: https://discord.com/developers/docs/resources/webhook

‎notifier/events.rst

Lines changed: 0 additions & 74 deletions
This file was deleted.

0 commit comments

Comments
 (0)