Skip to content

[Notifier] Notifier docs merge #17723

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 23, 2023
Merged

[Notifier] Notifier docs merge #17723

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions _build/redirection_map
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -540,3 +540,6 @@
/components/yaml/yaml_format /components/yaml#yaml-format
/components/expression_language/syntax /components/expression_language#expression-language-syntax
/components/expression_language/extending /components/expression_language#expression-language-extending
/notifier/chatters /notifier#sending-chat-messages
/notifier/texters /notifier#sending-sms
/notifier/events /notifier#notifier-events
203 changes: 174 additions & 29 deletions notifier.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,6 @@ The notifier component supports the following channels:
API's tokens.

.. _notifier-sms-channel:
.. _notifier-texter-dsn:

SMS Channel
~~~~~~~~~~~
Expand Down Expand Up @@ -169,8 +168,47 @@ configure the ``texter_transports``:
;
};

.. _sending-sms:

The :class:`Symfony\\Component\\Notifier\\TexterInterface` class allows you to
send SMS messages::

// src/Controller/SecurityController.php
namespace App\Controller;

use Symfony\Component\Notifier\Message\SmsMessage;
use Symfony\Component\Notifier\TexterInterface;
use Symfony\Component\Routing\Annotation\Route;

class SecurityController
{
/**
* @Route("/login/success")
*/
public function loginSuccess(TexterInterface $texter)
{
$sms = new SmsMessage(
// the phone number to send the SMS message to
'+1411111111',
// the message
'A new login was detected!'
);

$sentMessage = $texter->send($sms);

// ...
}
}

The ``send()`` method returns a variable of type
:class:`Symfony\\Component\\Notifier\\Message\\SentMessage` which provides
information such as the message ID and the original message contents.

.. versionadded:: 5.2

The ``SentMessage`` class was introduced in Symfony 5.2.

.. _notifier-chat-channel:
.. _notifier-chatter-dsn:

Chat Channel
~~~~~~~~~~~~
Expand All @@ -186,24 +224,24 @@ The chat channel is used to send chat messages to users by using
:class:`Symfony\\Component\\Notifier\\Chatter` classes. Symfony provides
integration with these chat services:

============== ==================================== =============================================================================
Service Package DSN
============== ==================================== =============================================================================
AmazonSns ``symfony/amazon-sns-notifier`` ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION``
Discord ``symfony/discord-notifier`` ``discord://TOKEN@default?webhook_id=ID``
FakeChat ``symfony/fake-chat-notifier`` ``fakechat+email://default?to=TO&from=FROM`` or ``fakechat+logger://default``
Firebase ``symfony/firebase-notifier`` ``firebase://USERNAME:PASSWORD@default``
Gitter ``symfony/gitter-notifier`` ``gitter://TOKEN@default?room_id=ROOM_ID``
GoogleChat ``symfony/google-chat-notifier`` ``googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?thread_key=THREAD_KEY``
LinkedIn ``symfony/linked-in-notifier`` ``linkedin://TOKEN:USER_ID@default``
Mattermost ``symfony/mattermost-notifier`` ``mattermost://ACCESS_TOKEN@HOST/PATH?channel=CHANNEL``
Mercure ``symfony/mercure-notifier`` ``mercure://HUB_ID?topic=TOPIC``
MicrosoftTeams ``symfony/microsoft-teams-notifier`` ``microsoftteams://default/PATH``
RocketChat ``symfony/rocket-chat-notifier`` ``rocketchat://TOKEN@ENDPOINT?channel=CHANNEL``
Slack ``symfony/slack-notifier`` ``slack://TOKEN@default?channel=CHANNEL``
Telegram ``symfony/telegram-notifier`` ``telegram://TOKEN@default?channel=CHAT_ID``
Zulip ``symfony/zulip-notifier`` ``zulip://EMAIL:TOKEN@HOST?channel=CHANNEL``
============== ==================================== =============================================================================
====================================== ==================================== =============================================================================
Service Package DSN
====================================== ==================================== =============================================================================
AmazonSns ``symfony/amazon-sns-notifier`` ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION``
:doc:`Discord <notifier/discord>` ``symfony/discord-notifier`` ``discord://TOKEN@default?webhook_id=ID``
FakeChat ``symfony/fake-chat-notifier`` ``fakechat+email://default?to=TO&from=FROM`` or ``fakechat+logger://default``
Firebase ``symfony/firebase-notifier`` ``firebase://USERNAME:PASSWORD@default``
Gitter ``symfony/gitter-notifier`` ``gitter://TOKEN@default?room_id=ROOM_ID``
GoogleChat ``symfony/google-chat-notifier`` ``googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?thread_key=THREAD_KEY``
LinkedIn ``symfony/linked-in-notifier`` ``linkedin://TOKEN:USER_ID@default``
Mattermost ``symfony/mattermost-notifier`` ``mattermost://ACCESS_TOKEN@HOST/PATH?channel=CHANNEL``
Mercure ``symfony/mercure-notifier`` ``mercure://HUB_ID?topic=TOPIC``
:doc:`MicrosoftTeams <notifier/teams>` ``symfony/microsoft-teams-notifier`` ``microsoftteams://default/PATH``
RocketChat ``symfony/rocket-chat-notifier`` ``rocketchat://TOKEN@ENDPOINT?channel=CHANNEL``
:doc:`Slack <notifier/slack>` ``symfony/slack-notifier`` ``slack://TOKEN@default?channel=CHANNEL``
:doc:`Telegram <notifier/telegram>` ``symfony/telegram-notifier`` ``telegram://TOKEN@default?channel=CHAT_ID``
Zulip ``symfony/zulip-notifier`` ``zulip://EMAIL:TOKEN@HOST?channel=CHANNEL``
====================================== ==================================== =============================================================================

.. versionadded:: 5.1

Expand Down Expand Up @@ -273,6 +311,41 @@ Chatters are configured using the ``chatter_transports`` setting:
;
};

.. _sending-chat-messages:

The :class:`Symfony\\Component\\Notifier\\ChatterInterface` class allows
you to send messages to chat services::

// src/Controller/CheckoutController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Notifier\ChatterInterface;
use Symfony\Component\Notifier\Message\ChatMessage;
use Symfony\Component\Routing\Annotation\Route;

class CheckoutController extends AbstractController
{
/**
* @Route("/checkout/thankyou")
*/
public function thankyou(ChatterInterface $chatter)
{
$message = (new ChatMessage('You got a new invoice for 15 EUR.'))
// if not set explicitly, the message is send to the
// default transport (the first one configured)
->transport('slack');

$sentMessage = $chatter->send($message);

// ...
}
}

The ``send()`` method returns a variable of type
:class:`Symfony\\Component\\Notifier\\Message\\SentMessage` which provides
information such as the message ID and the original message contents.

.. _notifier-email-channel:

Email Channel
Expand Down Expand Up @@ -750,18 +823,90 @@ all configured texter and chatter transports only in the ``dev`` (and/or
chatter_transports:
slack: 'null://null'

.. _notifier-events:

.. index::
single: Notifier; Events

Using Events
------------

.. versionadded:: 5.4

The ``MessageEvent``, ``FailedMessageEvent`` and ``SentMessageEvent`` were
introduced in Symfony 5.4.

The :class:`Symfony\\Component\\Notifier\\Transport`` class of the Notifier component
allows you to optionally hook into the lifecycle via events.

The ``MessageEvent::class`` Event
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Typical Purposes**: Doing something before the message is send (like logging
which message is going to be send, or displaying something about the event
to be executed.

Just before send the message, the event class ``MessageEvent`` is
dispatched. Listeners receive a
:class:`Symfony\\Component\\Notifier\\Event\\MessageEvent` event::

use Symfony\Component\Notifier\Event\MessageEvent;

$dispatcher->addListener(MessageEvent::class, function (MessageEvent $event) {
// gets the message instance
$message = $event->getMessage();

// log something
$this->logger(sprintf('Message with subject: %s will be send to %s, $message->getSubject(), $message->getRecipientId()'));
});

The ``FailedMessageEvent`` Event
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Typical Purposes**: Doing something before the exception is thrown (Retry to send the message or log additional information).

Whenever an exception is thrown while sending the message, the event class ``FailedMessageEvent`` is
dispatched. A listener can do anything useful before the exception is thrown.

Listeners receive a
:class:`Symfony\\Component\\Notifier\\Event\\FailedMessageEvent` event::

use Symfony\Component\Notifier\Event\FailedMessageEvent;

$dispatcher->addListener(FailedMessageEvent::class, function (FailedMessageEvent $event) {
// gets the message instance
$message = $event->getMessage();

// gets the error instance
$error = $event->getError();

// log something
$this->logger(sprintf('The message with subject: %s has not been sent successfully. The error is: %s, $message->getSubject(), $error->getMessage()'));
});

The ``SentMessageEvent`` Event
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Typical Purposes**: To perform some action when the message is successfully sent (like retrieve the id returned
when the message is sent).

After the message has been successfully sent, the event class ``SentMessageEvent`` is
dispatched. Listeners receive a
:class:`Symfony\\Component\\Notifier\\Event\\SentMessageEvent` event::

use Symfony\Component\Notifier\Event\SentMessageEvent;

$dispatcher->addListener(SentMessageEvent::class, function (SentMessageEvent $event) {
// gets the message instance
$message = $event->getOriginalMessage();

// log something
$this->logger(sprintf('The message has been successfully sent and have id: %s, $message->getMessageId()'));
});

.. TODO
.. - Using the message bus for asynchronous notification
.. - Describe notifier monolog handler
.. - Describe notification_on_failed_messages integration

Learn more
----------

.. toctree::
:maxdepth: 1
:glob:

notifier/*

.. _`RFC 3986`: https://www.ietf.org/rfc/rfc3986.txt
Loading