minor #878 [Notify] Using Chatter in the docs to show how to use MercureOptions to pass topics (weaverryan)

This PR was merged into the 2.x branch.

Discussion
----------

[Notify] Using Chatter in the docs to show how to use MercureOptions to pass topics

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| Tickets       | Fix #876
| License       | MIT

Hi!

Using `NotifierInterface` is just a shortcut if you need to send a notification to multiple channels. In this case, Mercure only supports chatter types anyways. Using Chatter directly gives us control to choose the topics, which is much more realistic.

Cheers!

Commits
-------

4cbc4ca [Notify] Using Chatter in the docs to show how to use MercureOptions to pass topics

Author: weaverryan

src/Notify/doc/index.rst

@@ -42,46 +42,46 @@ properly configured notifier transport:
             chatter_transports:
                myMercureChatter: '%env(MERCURE_DSN)%'
 
-.. note::
-
-   It is possible to specify the topics to send the notification in the ``MERCURE_DSN``
-   environment variable by specifying the ``topics`` query parameter.
-   Otherwise, notifications will be sent to ``https://symfony.com/notifier`` topic.
-
 Then, you can inject the ``NotifierInterface`` service and send messages on the ``chat/myMercureChatter`` channel::
 
     // ...
-    use Symfony\Component\Notifier\Notification\Notification;
-    use Symfony\Component\Notifier\NotifierInterface;
+    use Symfony\Component\Notifier\ChatterInterface;
+    use Symfony\Component\Notifier\Message\ChatMessage;
 
     #[AsCommand(name: 'app:flash-sales:announce')]
     class AnnounceFlashSalesCommand extends Command
     {
-        public function __construct(private NotifierInterface $notifier)
+        public function __construct(private ChatterInterface $chatter)
         {
             parent::__construct();
         }
 
         protected function execute(InputInterface $input, OutputInterface $output): int
         {
-            $this->notifier->send(new Notification('Flash sales has been started!', ['chat/myMercureChatter']));
+            $message = (new ChatMessage(
+                'Flash sales has been started!',
+                new MercureOptions(['/chat/flash-sales'])
+            ))->transport('myMercureChatter');
+
+            $this->chatter->send($message);
 
             return 0;
         }
     }
 
-Finally, to "listen" and trigger the notifications in the user's browser,
-call the ``stream_notifications()`` Twig function anywhere on the page:
+The ``chat/flash-sales`` is the Mercure topic the message will be sent to.
+The final step is to "listen" to that topic and trigger the notifications
+in the user's browser. To do that, call the ``stream_notifications()`` Twig
+function anywhere on the page:
 
 .. code-block:: twig
 
-    {{ stream_notifications() }}
-    {{ stream_notifications(['/my/topic/1', '/my/topic/2']) }}
+    {{ stream_notifications(['/chat/flash-sales']) }}
 
 .. note::
 
-   Calling ``stream_notifications()`` without parameter will fallback to the
-   following unique topic: ``https://symfony.com/notifier``.
+   Calling ``stream_notifications()`` without a parameter will default
+   to the ``https://symfony.com/notifier`` topic.
 
 Enjoy your server-sent native notifications!
 

ux.symfony.com/.env

@@ -39,5 +39,5 @@ DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db"
 ###< doctrine/doctrine-bundle ###
 
 ###> symfony/mercure-notifier ###
-MERCURE_DSN=mercure://default?topic=/demo/notifier
+MERCURE_DSN=mercure://default
 ###< symfony/mercure-notifier ###

ux.symfony.com/config/packages/notifier.yaml

@@ -1,6 +1,7 @@
 framework:
     notifier:
         chatter_transports:
+            # MERCURE_DSN is defined in .env or should be set by you
             custom_mercure_chatter_transport: '%env(MERCURE_DSN)%'
         #    slack: '%env(SLACK_DSN)%'
         #    telegram: '%env(TELEGRAM_DSN)%'

ux.symfony.com/src/Controller/NotifierController.php

@@ -4,17 +4,17 @@
 
 use App\Form\SendNotificationForm;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-use Symfony\Component\Asset\Packages;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
-use Symfony\Component\Notifier\Notification\Notification;
-use Symfony\Component\Notifier\NotifierInterface;
+use Symfony\Component\Notifier\Bridge\Mercure\MercureOptions;
+use Symfony\Component\Notifier\ChatterInterface;
+use Symfony\Component\Notifier\Message\ChatMessage;
 use Symfony\Component\Routing\Annotation\Route;
 
 class NotifierController extends AbstractController
 {
     #[Route('/notify', name: 'app_notify')]
-    public function notify(Request $request, NotifierInterface $notifier): Response
+    public function notify(Request $request, ChatterInterface $chatter): Response
     {
         $form = $this->createForm(SendNotificationForm::class);
 
@@ -24,9 +24,11 @@ public function notify(Request $request, NotifierInterface $notifier): Response
             $message = SendNotificationForm::getTextChoices()[$form->getData()['message']];
 
             // custom_mercure_chatter_transport is configured in config/packages/notifier.yaml
-            // it ultimately points to "mercure://default?topic=/demo/notifier"
-            $notification = new Notification($message, ['chat/custom_mercure_chatter_transport']);
-            $notifier->send($notification);
+            $message = (new ChatMessage(
+                $message,
+                new MercureOptions(['/demo/notifier'])
+            ))->transport('custom_mercure_chatter_transport');
+            $chatter->send($message);
 
             return $this->redirectToRoute('app_notify');
         }