feature #36611 Add Notifier SentMessage (jeremyFreeAgent)

This PR was squashed before being merged into the 5.2-dev branch.

Discussion
----------

Add Notifier SentMessage

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       |
| License       | MIT
| Doc PR        | symfony/symfony-docs#13624

Like Mailer, Notifier returns now a SentMessage that contains the messageId (returned by the provider in the response). It contains also the body of the response as array to have more info about price, number of sms sent, status and so on.

- [x] apply to bridges

Commits
-------

5a6f0537ec Add Notifier SentMessage

Author: fabpot

CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+5.2.0
+-----
+
+ * [BC BREAK] The `TransportInterface::send()` and `AbstractTransport::doSend()` methods changed to return a `SentMessage` instance instead of `void`.
+
 5.1.0
 -----
 

Chatter.php

@@ -16,6 +16,7 @@
 use Symfony\Component\Messenger\MessageBusInterface;
 use Symfony\Component\Notifier\Event\MessageEvent;
 use Symfony\Component\Notifier\Message\MessageInterface;
+use Symfony\Component\Notifier\Message\SentMessage;
 use Symfony\Component\Notifier\Transport\TransportInterface;
 use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
 
@@ -47,12 +48,10 @@ public function supports(MessageInterface $message): bool
         return $this->transport->supports($message);
     }
 
-    public function send(MessageInterface $message): void
+    public function send(MessageInterface $message): SentMessage
     {
         if (null === $this->bus) {
-            $this->transport->send($message);
-
-            return;
+            return $this->transport->send($message);
         }
 
         if (null !== $this->dispatcher) {

Message/SentMessage.php

@@ -0,0 +1,50 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Notifier\Message;
+
+/**
+ * @author Jérémy Romey <[email protected]>
+ *
+ * @experimental in 5.2
+ */
+final class SentMessage
+{
+    private $original;
+    private $transport;
+    private $messageId;
+
+    public function __construct(MessageInterface $original, string $transport)
+    {
+        $this->original = $original;
+        $this->transport = $transport;
+    }
+
+    public function getOriginalMessage(): MessageInterface
+    {
+        return $this->original;
+    }
+
+    public function getTransport(): string
+    {
+        return $this->transport;
+    }
+
+    public function setMessageId(string $id): void
+    {
+        $this->messageId = $id;
+    }
+
+    public function getMessageId(): ?string
+    {
+        return $this->messageId;
+    }
+}

Tests/Transport/TransportsTest.php

@@ -15,6 +15,7 @@
 use Symfony\Component\Notifier\Exception\InvalidArgumentException;
 use Symfony\Component\Notifier\Exception\LogicException;
 use Symfony\Component\Notifier\Message\ChatMessage;
+use Symfony\Component\Notifier\Message\SentMessage;
 use Symfony\Component\Notifier\Transport\TransportInterface;
 use Symfony\Component\Notifier\Transport\Transports;
 
@@ -30,9 +31,12 @@ public function testSendToTransportDefinedByMessage(): void
 
         $one->method('supports')->with($message)->willReturn(true);
 
-        $one->expects($this->once())->method('send');
+        $one->expects($this->once())->method('send')->willReturn(new SentMessage($message, 'one'));
 
-        $transports->send($message);
+        $sentMessage = $transports->send($message);
+
+        $this->assertSame($message, $sentMessage->getOriginalMessage());
+        $this->assertSame('one', $sentMessage->getTransport());
     }
 
     public function testSendToFirstSupportedTransportIfMessageDoesNotDefineATransport(): void
@@ -47,10 +51,16 @@ public function testSendToFirstSupportedTransportIfMessageDoesNotDefineATranspor
         $one->method('supports')->with($message)->willReturn(false);
         $two->method('supports')->with($message)->willReturn(true);
 
+        $one->method('send')->with($message)->willReturn(new SentMessage($message, 'one'));
+        $two->method('send')->with($message)->willReturn(new SentMessage($message, 'two'));
+
         $one->expects($this->never())->method('send');
-        $two->expects($this->once())->method('send');
+        $two->expects($this->once())->method('send')->willReturn(new SentMessage($message, 'two'));
 
-        $transports->send($message);
+        $sentMessage = $transports->send($message);
+
+        $this->assertSame($message, $sentMessage->getOriginalMessage());
+        $this->assertSame('two', $sentMessage->getTransport());
     }
 
     public function testThrowExceptionIfNoSupportedTransportWasFound(): void

Texter.php

@@ -16,6 +16,7 @@
 use Symfony\Component\Messenger\MessageBusInterface;
 use Symfony\Component\Notifier\Event\MessageEvent;
 use Symfony\Component\Notifier\Message\MessageInterface;
+use Symfony\Component\Notifier\Message\SentMessage;
 use Symfony\Component\Notifier\Transport\TransportInterface;
 use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
 
@@ -47,12 +48,10 @@ public function supports(MessageInterface $message): bool
         return $this->transport->supports($message);
     }
 
-    public function send(MessageInterface $message): void
+    public function send(MessageInterface $message): SentMessage
     {
         if (null === $this->bus) {
-            $this->transport->send($message);
-
-            return;
+            return $this->transport->send($message);
         }
 
         if (null !== $this->dispatcher) {

Transport/AbstractTransport.php

@@ -17,6 +17,7 @@
 use Symfony\Component\Notifier\Event\MessageEvent;
 use Symfony\Component\Notifier\Exception\LogicException;
 use Symfony\Component\Notifier\Message\MessageInterface;
+use Symfony\Component\Notifier\Message\SentMessage;
 use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 
@@ -69,16 +70,16 @@ public function setPort(?int $port): self
         return $this;
     }
 
-    public function send(MessageInterface $message): void
+    public function send(MessageInterface $message): SentMessage
     {
         if (null !== $this->dispatcher) {
             $this->dispatcher->dispatch(new MessageEvent($message));
         }
 
-        $this->doSend($message);
+        return $this->doSend($message);
     }
 
-    abstract protected function doSend(MessageInterface $message): void;
+    abstract protected function doSend(MessageInterface $message): SentMessage;
 
     protected function getEndpoint(): ?string
     {

Transport/NullTransport.php

@@ -15,6 +15,7 @@
 use Symfony\Component\EventDispatcher\LegacyEventDispatcherProxy;
 use Symfony\Component\Notifier\Event\MessageEvent;
 use Symfony\Component\Notifier\Message\MessageInterface;
+use Symfony\Component\Notifier\Message\SentMessage;
 use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
 
 /**
@@ -31,11 +32,13 @@ public function __construct(EventDispatcherInterface $dispatcher = null)
         $this->dispatcher = class_exists(Event::class) ? LegacyEventDispatcherProxy::decorate($dispatcher) : $dispatcher;
     }
 
-    public function send(MessageInterface $message): void
+    public function send(MessageInterface $message): SentMessage
     {
         if (null !== $this->dispatcher) {
             $this->dispatcher->dispatch(new MessageEvent($message));
         }
+
+        return new SentMessage($message, (string) $this);
     }
 
     public function __toString(): string

Transport/RoundRobinTransport.php

@@ -15,6 +15,7 @@
 use Symfony\Component\Notifier\Exception\RuntimeException;
 use Symfony\Component\Notifier\Exception\TransportExceptionInterface;
 use Symfony\Component\Notifier\Message\MessageInterface;
+use Symfony\Component\Notifier\Message\SentMessage;
 
 /**
  * Uses several Transports using a round robin algorithm.
@@ -63,13 +64,11 @@ public function supports(MessageInterface $message): bool
         return false;
     }
 
-    public function send(MessageInterface $message): void
+    public function send(MessageInterface $message): SentMessage
     {
         while ($transport = $this->getNextTransport($message)) {
             try {
-                $transport->send($message);
-
-                return;
+                return $transport->send($message);
             } catch (TransportExceptionInterface $e) {
                 $this->deadTransports[$transport] = microtime(true);
             }

Transport/TransportInterface.php

@@ -13,6 +13,7 @@
 
 use Symfony\Component\Notifier\Exception\TransportExceptionInterface;
 use Symfony\Component\Notifier\Message\MessageInterface;
+use Symfony\Component\Notifier\Message\SentMessage;
 
 /**
  * @author Fabien Potencier <[email protected]>
@@ -24,7 +25,7 @@ interface TransportInterface
     /**
      * @throws TransportExceptionInterface
      */
-    public function send(MessageInterface $message): void;
+    public function send(MessageInterface $message): SentMessage;
 
     public function supports(MessageInterface $message): bool;
 

Transport/Transports.php

@@ -14,6 +14,7 @@
 use Symfony\Component\Notifier\Exception\InvalidArgumentException;
 use Symfony\Component\Notifier\Exception\LogicException;
 use Symfony\Component\Notifier\Message\MessageInterface;
+use Symfony\Component\Notifier\Message\SentMessage;
 
 /**
  * @author Fabien Potencier <[email protected]>
@@ -51,17 +52,14 @@ public function supports(MessageInterface $message): bool
         return false;
     }
 
-    public function send(MessageInterface $message): void
+    public function send(MessageInterface $message): SentMessage
     {
         if (!$transport = $message->getTransport()) {
             foreach ($this->transports as $transport) {
                 if ($transport->supports($message)) {
-                    $transport->send($message);
-
-                    return;
+                    return $transport->send($message);
                 }
             }
-
             throw new LogicException(sprintf('None of the available transports support the given message (available transports: "%s").', implode('", "', array_keys($this->transports))));
         }
 
@@ -73,6 +71,6 @@ public function send(MessageInterface $message): void
             throw new LogicException(sprintf('The "%s" transport does not support the given message.', $transport));
         }
 
-        $this->transports[$transport]->send($message);
+        return $this->transports[$transport]->send($message);
     }
 }