feature #32916 [Mailer] Add a name to the transports (fabpot)

This PR was merged into the 4.4 branch.

Discussion
----------

[Mailer] Add a name to the transports

| Q             | A
| ------------- | ---
| Branch?       | 4.4
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no     <!-- see https://symfony.com/bc -->
| Deprecations? | no <!-- please update UPGRADE-*.md and src/**/CHANGELOG.md files -->
| Tests pass?   | yes    <!-- please add some, will be required by reviewers -->
| Fixed tickets | n/a
| License       | MIT
| Doc PR        | n/a

Having a name for Transports helps identify them (useful for instance in the profiler when one uses several mailers).

Commits
-------

2412dfe [Mailer] added a name to the transport

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/MailerTest.php

@@ -42,6 +42,11 @@ public function __construct(EventDispatcherInterface $eventDispatcher, LoggerInt
                 $this->onDoSend = $onDoSend;
             }
 
+            public function getName(): string
+            {
+                return 'dummy://local';
+            }
+
             protected function doSend(SentMessage $message): void
             {
                 $onDoSend = $this->onDoSend;

src/Symfony/Bundle/FrameworkBundle/composer.json

@@ -74,6 +74,7 @@
         "symfony/dom-crawler": "<4.3",
         "symfony/form": "<4.3",
         "symfony/lock": "<4.4",
+        "symfony/mailer": "<4.4",
         "symfony/messenger": "<4.3",
         "symfony/property-info": "<3.4",
         "symfony/serializer": "<4.2",

src/Symfony/Component/Mailer/Bridge/Amazon/Transport/SesApiTransport.php

@@ -43,6 +43,11 @@ public function __construct(string $accessKey, string $secretKey, string $region
         parent::__construct($client, $dispatcher, $logger);
     }
 
+    public function getName(): string
+    {
+        return sprintf('api://%s@ses?region=%s', $this->accessKey, $this->region);
+    }
+
     protected function doSendApi(Email $email, SmtpEnvelope $envelope): ResponseInterface
     {
         $date = gmdate('D, d M Y H:i:s e');

src/Symfony/Component/Mailer/Bridge/Amazon/Transport/SesHttpTransport.php

@@ -42,6 +42,11 @@ public function __construct(string $accessKey, string $secretKey, string $region
         parent::__construct($client, $dispatcher, $logger);
     }
 
+    public function getName(): string
+    {
+        return sprintf('http://%s@ses?region=%s', $this->accessKey, $this->region);
+    }
+
     protected function doSendHttp(SentMessage $message): ResponseInterface
     {
         $date = gmdate('D, d M Y H:i:s e');

src/Symfony/Component/Mailer/Bridge/Mailchimp/Transport/MandrillApiTransport.php

@@ -36,6 +36,11 @@ public function __construct(string $key, HttpClientInterface $client = null, Eve
         parent::__construct($client, $dispatcher, $logger);
     }
 
+    public function getName(): string
+    {
+        return sprintf('api://mandrill');
+    }
+
     protected function doSendApi(Email $email, SmtpEnvelope $envelope): ResponseInterface
     {
         $response = $this->client->request('POST', self::ENDPOINT, [

src/Symfony/Component/Mailer/Bridge/Mailchimp/Transport/MandrillHttpTransport.php

@@ -34,6 +34,11 @@ public function __construct(string $key, HttpClientInterface $client = null, Eve
         parent::__construct($client, $dispatcher, $logger);
     }
 
+    public function getName(): string
+    {
+        return sprintf('http://mandrill');
+    }
+
     protected function doSendHttp(SentMessage $message): ResponseInterface
     {
         $envelope = $message->getEnvelope();

src/Symfony/Component/Mailer/Bridge/Mailgun/Transport/MailgunApiTransport.php

@@ -41,6 +41,11 @@ public function __construct(string $key, string $domain, string $region = null,
         parent::__construct($client, $dispatcher, $logger);
     }
 
+    public function getName(): string
+    {
+        return sprintf('api://%s@mailgun?region=%s', $this->domain, $this->region);
+    }
+
     protected function doSendApi(Email $email, SmtpEnvelope $envelope): ResponseInterface
     {
         $body = new FormDataPart($this->getPayload($email, $envelope));

src/Symfony/Component/Mailer/Bridge/Mailgun/Transport/MailgunHttpTransport.php

@@ -40,6 +40,11 @@ public function __construct(string $key, string $domain, string $region = null,
         parent::__construct($client, $dispatcher, $logger);
     }
 
+    public function getName(): string
+    {
+        return sprintf('http://%s@mailgun?region=%s', $this->domain, $this->region);
+    }
+
     protected function doSendHttp(SentMessage $message): ResponseInterface
     {
         $body = new FormDataPart([

src/Symfony/Component/Mailer/Bridge/Postmark/Transport/PostmarkApiTransport.php

@@ -36,6 +36,11 @@ public function __construct(string $key, HttpClientInterface $client = null, Eve
         parent::__construct($client, $dispatcher, $logger);
     }
 
+    public function getName(): string
+    {
+        return sprintf('api://postmark');
+    }
+
     protected function doSendApi(Email $email, SmtpEnvelope $envelope): ResponseInterface
     {
         $response = $this->client->request('POST', self::ENDPOINT, [

src/Symfony/Component/Mailer/Bridge/Sendgrid/Transport/SendgridApiTransport.php

@@ -37,6 +37,11 @@ public function __construct(string $key, HttpClientInterface $client = null, Eve
         parent::__construct($client, $dispatcher, $logger);
     }
 
+    public function getName(): string
+    {
+        return sprintf('api://sendgrid');
+    }
+
     protected function doSendApi(Email $email, SmtpEnvelope $envelope): ResponseInterface
     {
         $response = $this->client->request('POST', self::ENDPOINT, [

src/Symfony/Component/Mailer/CHANGELOG.md

@@ -4,6 +4,7 @@ CHANGELOG
 4.4.0
 -----
 
+ * [BC BREAK] `TransportInterface` has a new `getName()` method
  * [BC BREAK] Classes `AbstractApiTransport` and `AbstractHttpTransport` moved under `Transport` sub-namespace.
  * [BC BREAK] Transports depend on `Symfony\Contracts\EventDispatcher\EventDispatcherInterface`
    instead of `Symfony\Component\EventDispatcher\EventDispatcherInterface`.

src/Symfony/Component/Mailer/Test/TransportFactoryTestCase.php

@@ -69,6 +69,9 @@ public function testCreate(Dsn $dsn, TransportInterface $transport): void
         $factory = $this->getFactory();
 
         $this->assertEquals($transport, $factory->create($dsn));
+        if ('smtp' !== $dsn->getScheme()) {
+            $this->assertStringMatchesFormat($dsn->getScheme().'://%S'.$dsn->getHost().'%S', $transport->getName());
+        }
     }
 
     /**

src/Symfony/Component/Mailer/Tests/Transport/FailoverTransportTest.php

@@ -29,6 +29,16 @@ public function testSendNoTransports()
         new FailoverTransport([]);
     }
 
+    public function testGetName()
+    {
+        $t1 = $this->createMock(TransportInterface::class);
+        $t1->expects($this->once())->method('getName')->willReturn('t1://local');
+        $t2 = $this->createMock(TransportInterface::class);
+        $t2->expects($this->once())->method('getName')->willReturn('t2://local');
+        $t = new FailoverTransport([$t1, $t2]);
+        $this->assertEquals('t1://local || t2://local', $t->getName());
+    }
+
     public function testSendFirstWork()
     {
         $t1 = $this->createMock(TransportInterface::class);

src/Symfony/Component/Mailer/Tests/Transport/NullTransportTest.php

@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Mailer\Tests\Transport;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Mailer\Transport\NullTransport;
+
+class NullTransportTest extends TestCase
+{
+    public function testName()
+    {
+        $t = new NullTransport();
+        $this->assertEquals('smtp://null', $t->getName());
+    }
+}

src/Symfony/Component/Mailer/Tests/Transport/RoundRobinTransportTest.php

@@ -28,6 +28,16 @@ public function testSendNoTransports()
         new RoundRobinTransport([]);
     }
 
+    public function testGetName()
+    {
+        $t1 = $this->createMock(TransportInterface::class);
+        $t1->expects($this->once())->method('getName')->willReturn('t1://local');
+        $t2 = $this->createMock(TransportInterface::class);
+        $t2->expects($this->once())->method('getName')->willReturn('t2://local');
+        $t = new RoundRobinTransport([$t1, $t2]);
+        $this->assertEquals('t1://local && t2://local', $t->getName());
+    }
+
     public function testSendAlternate()
     {
         $t1 = $this->createMock(TransportInterface::class);

src/Symfony/Component/Mailer/Tests/Transport/SendmailTransportTest.php

@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Mailer\Tests\Transport;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Mailer\Transport\SendmailTransport;
+
+class SendmailTransportTest extends TestCase
+{
+    public function testName()
+    {
+        $t = new SendmailTransport();
+        $this->assertEquals('smtp://sendmail', $t->getName());
+    }
+}

src/Symfony/Component/Mailer/Tests/Transport/Smtp/SmtpTransportTest.php

@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Mailer\Tests\Transport\Smtp;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Mailer\Transport\Smtp\SmtpTransport;
+use Symfony\Component\Mailer\Transport\Smtp\Stream\SocketStream;
+
+class SmtpTransportTest extends TestCase
+{
+    public function testName()
+    {
+        $t = new SmtpTransport();
+        $this->assertEquals('smtp://localhost:25', $t->getName());
+
+        $t = new SmtpTransport((new SocketStream())->setHost('127.0.0.1')->setPort(2525));
+        $this->assertEquals('smtp://127.0.0.1:2525', $t->getName());
+    }
+}

src/Symfony/Component/Mailer/Tests/TransportTest.php

@@ -68,6 +68,11 @@ public function send(RawMessage $message, SmtpEnvelope $envelope = null): ?SentM
     {
         throw new \BadMethodCallException('This method newer should be called.');
     }
+
+    public function getName(): string
+    {
+        return sprintf('dummy://local');
+    }
 }
 
 class DummyTransportFactory implements Transport\TransportFactoryInterface

src/Symfony/Component/Mailer/Transport/AbstractTransport.php

@@ -39,6 +39,8 @@ public function __construct(EventDispatcherInterface $dispatcher = null, LoggerI
         $this->logger = $logger ?: new NullLogger();
     }
 
+    abstract public function getName(): string;
+
     /**
      * Sets the maximum number of messages to send per second (0 to disable).
      */

src/Symfony/Component/Mailer/Transport/FailoverTransport.php

@@ -28,4 +28,9 @@ protected function getNextTransport(): ?TransportInterface
 
         return $this->currentTransport;
     }
+
+    protected function getNameSymbol(): string
+    {
+        return '||';
+    }
 }

src/Symfony/Component/Mailer/Transport/NullTransport.php

@@ -23,4 +23,9 @@ final class NullTransport extends AbstractTransport
     protected function doSend(SentMessage $message): void
     {
     }
+
+    public function getName(): string
+    {
+        return 'smtp://null';
+    }
 }

src/Symfony/Component/Mailer/Transport/RoundRobinTransport.php

@@ -56,6 +56,13 @@ public function send(RawMessage $message, SmtpEnvelope $envelope = null): ?SentM
         throw new TransportException('All transports failed.');
     }
 
+    public function getName(): string
+    {
+        return implode(' '.$this->getNameSymbol().' ', array_map(function (TransportInterface $transport) {
+            return $transport->getName();
+        }, $this->transports));
+    }
+
     /**
      * Rotates the transport list around and returns the first instance.
      */
@@ -90,6 +97,11 @@ protected function isTransportDead(TransportInterface $transport): bool
         return $this->deadTransports->contains($transport);
     }
 
+    protected function getNameSymbol(): string
+    {
+        return '&&';
+    }
+
     private function moveCursor(int $cursor): int
     {
         return ++$cursor >= \count($this->transports) ? 0 : $cursor;

src/Symfony/Component/Mailer/Transport/SendmailTransport.php

@@ -73,6 +73,11 @@ public function send(RawMessage $message, SmtpEnvelope $envelope = null): ?SentM
         return parent::send($message, $envelope);
     }
 
+    public function getName(): string
+    {
+        return $this->transport->getName();
+    }
+
     protected function doSend(SentMessage $message): void
     {
         $this->getLogger()->debug(sprintf('Email transport "%s" starting', __CLASS__));

src/Symfony/Component/Mailer/Transport/Smtp/SmtpTransport.php

@@ -126,6 +126,15 @@ public function send(RawMessage $message, SmtpEnvelope $envelope = null): ?SentM
         return $message;
     }
 
+    public function getName(): string
+    {
+        if ($this->stream instanceof SocketStream) {
+            return sprintf('smtp://%s:%d', $this->stream->getHost(), $this->stream->getPort());
+        }
+
+        return sprintf('smtp://sendmail');
+    }
+
     /**
      * Runs a command against the stream, expecting the given response codes.
      *

src/Symfony/Component/Mailer/Transport/TransportInterface.php

@@ -30,4 +30,6 @@ interface TransportInterface
      * @throws TransportExceptionInterface
      */
     public function send(RawMessage $message, SmtpEnvelope $envelope = null): ?SentMessage;
+
+    public function getName(): string;
 }