Merge docs about Notifier

Author: fabpot

notifier.rst

@@ -46,7 +46,6 @@ The notifier component supports the following channels:
     API's tokens.
 
 .. _notifier-sms-channel:
-.. _notifier-texter-dsn:
 
 SMS Channel
 ~~~~~~~~~~~
@@ -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
 ~~~~~~~~~~~~
@@ -273,6 +311,39 @@ Chatters are configured using the ``chatter_transports`` setting:
             ;
         };
 
+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
@@ -748,18 +819,88 @@ all configured texter and chatter transports only in the ``dev`` (and/or
             chatter_transports:
                 slack: 'null://null'
 
+.. 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

notifier/chatters.rst

@@ -4,52 +4,6 @@
 How to send Chat Messages
 =========================
 
-.. versionadded:: 5.0
-
-    The Notifier component was introduced in Symfony 5.0.
-
-The :class:`Symfony\\Component\\Notifier\\ChatterInterface` class allows
-you to send messages to chat services like Slack or Telegram::
-
-    // 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.
-
-.. versionadded:: 5.2
-
-    The ``SentMessage`` class was introduced in Symfony 5.2.
-
-.. seealso::
-
-    Read :ref:`the main Notifier guide <notifier-chatter-dsn>` to see how
-    to configure the different transports.
-
 Adding Interactions to a Slack Message
 --------------------------------------