Skip to content

Commit 6ae741f

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '6.0' into 6.1
* 6.0: [Notifier] Notifier docs merge
2 parents 4433747 + 14392c4 commit 6ae741f

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
@@ -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: 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
~~~~~~~~~~~
@@ -153,8 +152,41 @@ configure the ``texter_transports``:
153152
;
154153
};
155154
155+
.. _sending-sms:
156+
157+
The :class:`Symfony\\Component\\Notifier\\TexterInterface` class allows you to
158+
send SMS messages::
159+
160+
// src/Controller/SecurityController.php
161+
namespace App\Controller;
162+
163+
use Symfony\Component\Notifier\Message\SmsMessage;
164+
use Symfony\Component\Notifier\TexterInterface;
165+
use Symfony\Component\Routing\Annotation\Route;
166+
167+
class SecurityController
168+
{
169+
#[Route('/login/success')]
170+
public function loginSuccess(TexterInterface $texter)
171+
{
172+
$sms = new SmsMessage(
173+
// the phone number to send the SMS message to
174+
'+1411111111',
175+
// the message
176+
'A new login was detected!'
177+
);
178+
179+
$sentMessage = $texter->send($sms);
180+
181+
// ...
182+
}
183+
}
184+
185+
The ``send()`` method returns a variable of type
186+
:class:`Symfony\\Component\\Notifier\\Message\\SentMessage` which provides
187+
information such as the message ID and the original message contents.
188+
156189
.. _notifier-chat-channel:
157-
.. _notifier-chatter-dsn:
158190

159191
Chat Channel
160192
~~~~~~~~~~~~
@@ -170,24 +202,24 @@ The chat channel is used to send chat messages to users by using
170202
:class:`Symfony\\Component\\Notifier\\Chatter` classes. Symfony provides
171203
integration with these chat services:
172204

173-
============== ==================================== =============================================================================
174-
Service Package DSN
175-
============== ==================================== =============================================================================
176-
AmazonSns ``symfony/amazon-sns-notifier`` ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION``
177-
Discord ``symfony/discord-notifier`` ``discord://TOKEN@default?webhook_id=ID``
178-
FakeChat ``symfony/fake-chat-notifier`` ``fakechat+email://default?to=TO&from=FROM`` or ``fakechat+logger://default``
179-
Firebase ``symfony/firebase-notifier`` ``firebase://USERNAME:PASSWORD@default``
180-
Gitter ``symfony/gitter-notifier`` ``gitter://TOKEN@default?room_id=ROOM_ID``
181-
GoogleChat ``symfony/google-chat-notifier`` ``googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?thread_key=THREAD_KEY``
182-
LinkedIn ``symfony/linked-in-notifier`` ``linkedin://TOKEN:USER_ID@default``
183-
Mattermost ``symfony/mattermost-notifier`` ``mattermost://ACCESS_TOKEN@HOST/PATH?channel=CHANNEL``
184-
Mercure ``symfony/mercure-notifier`` ``mercure://HUB_ID?topic=TOPIC``
185-
MicrosoftTeams ``symfony/microsoft-teams-notifier`` ``microsoftteams://default/PATH``
186-
RocketChat ``symfony/rocket-chat-notifier`` ``rocketchat://TOKEN@ENDPOINT?channel=CHANNEL``
187-
Slack ``symfony/slack-notifier`` ``slack://TOKEN@default?channel=CHANNEL``
188-
Telegram ``symfony/telegram-notifier`` ``telegram://TOKEN@default?channel=CHAT_ID``
189-
Zulip ``symfony/zulip-notifier`` ``zulip://EMAIL:TOKEN@HOST?channel=CHANNEL``
190-
============== ==================================== =============================================================================
205+
====================================== ==================================== =============================================================================
206+
Service Package DSN
207+
====================================== ==================================== =============================================================================
208+
AmazonSns ``symfony/amazon-sns-notifier`` ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION``
209+
:doc:`Discord <notifier/discord>` ``symfony/discord-notifier`` ``discord://TOKEN@default?webhook_id=ID``
210+
FakeChat ``symfony/fake-chat-notifier`` ``fakechat+email://default?to=TO&from=FROM`` or ``fakechat+logger://default``
211+
Firebase ``symfony/firebase-notifier`` ``firebase://USERNAME:PASSWORD@default``
212+
Gitter ``symfony/gitter-notifier`` ``gitter://TOKEN@default?room_id=ROOM_ID``
213+
GoogleChat ``symfony/google-chat-notifier`` ``googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?thread_key=THREAD_KEY``
214+
LinkedIn ``symfony/linked-in-notifier`` ``linkedin://TOKEN:USER_ID@default``
215+
Mattermost ``symfony/mattermost-notifier`` ``mattermost://ACCESS_TOKEN@HOST/PATH?channel=CHANNEL``
216+
Mercure ``symfony/mercure-notifier`` ``mercure://HUB_ID?topic=TOPIC``
217+
:doc:`MicrosoftTeams <notifier/teams>` ``symfony/microsoft-teams-notifier`` ``microsoftteams://default/PATH``
218+
RocketChat ``symfony/rocket-chat-notifier`` ``rocketchat://TOKEN@ENDPOINT?channel=CHANNEL``
219+
:doc:`Slack <notifier/slack>` ``symfony/slack-notifier`` ``slack://TOKEN@default?channel=CHANNEL``
220+
:doc:`Telegram <notifier/telegram>` ``symfony/telegram-notifier`` ``telegram://TOKEN@default?channel=CHAT_ID``
221+
Zulip ``symfony/zulip-notifier`` ``zulip://EMAIL:TOKEN@HOST?channel=CHANNEL``
222+
====================================== ==================================== =============================================================================
191223

192224
Chatters are configured using the ``chatter_transports`` setting:
193225

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

243310
Email Channel
@@ -767,18 +834,87 @@ all configured texter and chatter transports only in the ``dev`` (and/or
767834
chatter_transports:
768835
slack: 'null://null'
769836
837+
.. _notifier-events:
838+
839+
.. index::
840+
single: Notifier; Events
841+
842+
Using Events
843+
------------
844+
845+
The :class:`Symfony\\Component\\Notifier\\Transport`` class of the Notifier component
846+
allows you to optionally hook into the lifecycle via events.
847+
848+
The ``MessageEvent::class`` Event
849+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
850+
851+
**Typical Purposes**: Doing something before the message is send (like logging
852+
which message is going to be send, or displaying something about the event
853+
to be executed.
854+
855+
Just before send the message, the event class ``MessageEvent`` is
856+
dispatched. Listeners receive a
857+
:class:`Symfony\\Component\\Notifier\\Event\\MessageEvent` event::
858+
859+
use Symfony\Component\Notifier\Event\MessageEvent;
860+
861+
$dispatcher->addListener(MessageEvent::class, function (MessageEvent $event) {
862+
// gets the message instance
863+
$message = $event->getMessage();
864+
865+
// log something
866+
$this->logger(sprintf('Message with subject: %s will be send to %s, $message->getSubject(), $message->getRecipientId()'));
867+
});
868+
869+
The ``FailedMessageEvent`` Event
870+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
871+
872+
**Typical Purposes**: Doing something before the exception is thrown
873+
(Retry to send the message or log additional information).
874+
875+
Whenever an exception is thrown while sending the message, the event class
876+
``FailedMessageEvent`` is dispatched. A listener can do anything useful before
877+
the exception is thrown.
878+
879+
Listeners receive a
880+
:class:`Symfony\\Component\\Notifier\\Event\\FailedMessageEvent` event::
881+
882+
use Symfony\Component\Notifier\Event\FailedMessageEvent;
883+
884+
$dispatcher->addListener(FailedMessageEvent::class, function (FailedMessageEvent $event) {
885+
// gets the message instance
886+
$message = $event->getMessage();
887+
888+
// gets the error instance
889+
$error = $event->getError();
890+
891+
// log something
892+
$this->logger(sprintf('The message with subject: %s has not been sent successfully. The error is: %s, $message->getSubject(), $error->getMessage()'));
893+
});
894+
895+
The ``SentMessageEvent`` Event
896+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
897+
898+
**Typical Purposes**: To perform some action when the message is successfully
899+
sent (like retrieve the id returned when the message is sent).
900+
901+
After the message has been successfully sent, the event class ``SentMessageEvent``
902+
is dispatched. Listeners receive a
903+
:class:`Symfony\\Component\\Notifier\\Event\\SentMessageEvent` event::
904+
905+
use Symfony\Component\Notifier\Event\SentMessageEvent;
906+
907+
$dispatcher->addListener(SentMessageEvent::class, function (SentMessageEvent $event) {
908+
// gets the message instance
909+
$message = $event->getOriginalMessage();
910+
911+
// log something
912+
$this->logger(sprintf('The message has been successfully sent and have id: %s, $message->getMessageId()'));
913+
});
914+
770915
.. TODO
771916
.. - Using the message bus for asynchronous notification
772917
.. - Describe notifier monolog handler
773918
.. - Describe notification_on_failed_messages integration
774919
775-
Learn more
776-
----------
777-
778-
.. toctree::
779-
:maxdepth: 1
780-
:glob:
781-
782-
notifier/*
783-
784920
.. _`RFC 3986`: https://www.ietf.org/rfc/rfc3986.txt

0 commit comments

Comments
 (0)