feature #42710 [Mailer] Added OhMySMTP Bridge (paul-oms)

This PR was squashed before being merged into the 5.4 branch.

Discussion
----------

[Mailer] Added OhMySMTP Bridge

This adds the https://ohmysmtp.com bridge to enable sending over the [OhMySMTP](https://ohmysmtp.com) API.

| Q             | A
| ------------- | ---
| Branch?       | 5.4 <!-- see below -->
| Bug fix?      | no
| New feature?  | yes <!-- please update src/**/CHANGELOG.md files -->
| Deprecations? | no <!-- please update UPGRADE-*.md and src/**/CHANGELOG.md files -->
| Tickets       | none <!-- prefix each issue number with "Fix #", no need to create an issue if none exist, explain below instead -->
| License       | MIT
| Doc PR        | symfony/symfony-docs#15747... <!-- required for new features -->
<!--
Replace this notice by a short README for your feature/bugfix. This will help people
understand your PR and can be used as a start for the documentation.

Additionally (see https://symfony.com/releases):
 - Always add tests and ensure they pass.
 - Never break backward compatibility (see https://symfony.com/bc).
 - Bug fixes must be submitted against the lowest maintained branch where they apply
   (lowest branches are regularly merged to upper ones so they get the fixes too.)
 - Features and deprecations must be submitted against branch 5.x.
 - Changelog entry should follow https://symfony.com/doc/current/contributing/code/conventions.html#writing-a-changelog-entry
-->

Commits
-------

ce72fd8 [Mailer] Added OhMySMTP Bridge

src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php

@@ -90,6 +90,7 @@
 use Symfony\Component\Mailer\Bridge\Mailchimp\Transport\MandrillTransportFactory;
 use Symfony\Component\Mailer\Bridge\Mailgun\Transport\MailgunTransportFactory;
 use Symfony\Component\Mailer\Bridge\Mailjet\Transport\MailjetTransportFactory;
+use Symfony\Component\Mailer\Bridge\OhMySmtp\Transport\OhMySmtpTransportFactory;
 use Symfony\Component\Mailer\Bridge\Postmark\Transport\PostmarkTransportFactory;
 use Symfony\Component\Mailer\Bridge\Sendgrid\Transport\SendgridTransportFactory;
 use Symfony\Component\Mailer\Bridge\Sendinblue\Transport\SendinblueTransportFactory;
@@ -2357,6 +2358,7 @@ private function registerMailerConfiguration(array $config, ContainerBuilder $co
             SendgridTransportFactory::class => 'mailer.transport_factory.sendgrid',
             SendinblueTransportFactory::class => 'mailer.transport_factory.sendinblue',
             SesTransportFactory::class => 'mailer.transport_factory.amazon',
+            OhMySmtpTransportFactory::class => 'mailer.transport_factory.ohmysmtp',
         ];
 
         foreach ($classToServices as $class => $service) {

src/Symfony/Bundle/FrameworkBundle/Resources/config/mailer_transports.php

@@ -16,6 +16,7 @@
 use Symfony\Component\Mailer\Bridge\Mailchimp\Transport\MandrillTransportFactory;
 use Symfony\Component\Mailer\Bridge\Mailgun\Transport\MailgunTransportFactory;
 use Symfony\Component\Mailer\Bridge\Mailjet\Transport\MailjetTransportFactory;
+use Symfony\Component\Mailer\Bridge\OhMySmtp\Transport\OhMySmtpTransportFactory;
 use Symfony\Component\Mailer\Bridge\Postmark\Transport\PostmarkTransportFactory;
 use Symfony\Component\Mailer\Bridge\Sendgrid\Transport\SendgridTransportFactory;
 use Symfony\Component\Mailer\Bridge\Sendinblue\Transport\SendinblueTransportFactory;
@@ -76,6 +77,10 @@
         ->parent('mailer.transport_factory.abstract')
         ->tag('mailer.transport_factory')
 
+        ->set('mailer.transport_factory.ohmysmtp', OhMySmtpTransportFactory::class)
+            ->parent('mailer.transport_factory.abstract')
+            ->tag('mailer.transport_factory')
+
         ->set('mailer.transport_factory.smtp', EsmtpTransportFactory::class)
             ->parent('mailer.transport_factory.abstract')
             ->tag('mailer.transport_factory', ['priority' => -100])

src/Symfony/Component/Mailer/Bridge/OhMySmtp/.gitattributes

@@ -0,0 +1,4 @@
+/Tests export-ignore
+/phpunit.xml.dist export-ignore
+/.gitattributes export-ignore
+/.gitignore export-ignore

src/Symfony/Component/Mailer/Bridge/OhMySmtp/.gitignore

@@ -0,0 +1,3 @@
+vendor/
+composer.lock
+phpunit.xml

src/Symfony/Component/Mailer/Bridge/OhMySmtp/CHANGELOG.md

@@ -0,0 +1,7 @@
+CHANGELOG
+=========
+
+5.4
+---
+
+ * Add the bridge

src/Symfony/Component/Mailer/Bridge/OhMySmtp/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2021 Fabien Potencier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

src/Symfony/Component/Mailer/Bridge/OhMySmtp/README.md

@@ -0,0 +1,24 @@
+OhMySMTP Bridge
+===============
+
+Provides [OhMySMTP](https://ohmysmtp.com) integration for Symfony Mailer.
+
+
+DSN example
+-----------
+
+```
+MAILER_DSN=ohmysmtp+api://API_TOKEN@default
+```
+
+where:
+ - `API_TOKEN` is your OhMySMTP API Token
+
+
+Resources
+---------
+
+ * [Contributing](https://symfony.com/doc/current/contributing/index.html)
+ * [Report issues](https://github.com/symfony/symfony/issues) and
+   [send Pull Requests](https://github.com/symfony/symfony/pulls)
+   in the [main Symfony repository](https://github.com/symfony/symfony)

src/Symfony/Component/Mailer/Bridge/OhMySmtp/Tests/Transport/OhMySmtpApiTransportTest.php

@@ -0,0 +1,143 @@
+<?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\Bridge\OhMySmtp\Tests\Transport;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\HttpClient\MockHttpClient;
+use Symfony\Component\HttpClient\Response\MockResponse;
+use Symfony\Component\Mailer\Bridge\OhMySmtp\Transport\OhMySmtpApiTransport;
+use Symfony\Component\Mailer\Envelope;
+use Symfony\Component\Mailer\Exception\HttpTransportException;
+use Symfony\Component\Mailer\Header\TagHeader;
+use Symfony\Component\Mime\Address;
+use Symfony\Component\Mime\Email;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+final class OhMySmtpApiTransportTest extends TestCase
+{
+    /**
+     * @dataProvider getTransportData
+     */
+    public function testToString(OhMySmtpApiTransport $transport, string $expected)
+    {
+        $this->assertSame($expected, (string) $transport);
+    }
+
+    public function getTransportData(): array
+    {
+        return [
+            [
+                new OhMySmtpApiTransport('KEY'),
+                'ohmysmtp+api://app.ohmysmtp.com/api/v1',
+            ],
+            [
+                (new OhMySmtpApiTransport('KEY'))->setHost('example.com'),
+                'ohmysmtp+api://example.com',
+            ],
+            [
+                (new OhMySmtpApiTransport('KEY'))->setHost('example.com')->setPort(99),
+                'ohmysmtp+api://example.com:99',
+            ],
+        ];
+    }
+
+    public function testCustomHeader()
+    {
+        $email = new Email();
+        $email->getHeaders()->addTextHeader('foo', 'bar');
+        $envelope = new Envelope(new Address('alice@system.com'), [new Address('bob@system.com')]);
+
+        $transport = new OhMySmtpApiTransport('ACCESS_KEY');
+        $method = new \ReflectionMethod(OhMySmtpApiTransport::class, 'getPayload');
+        $method->setAccessible(true);
+        $payload = $method->invoke($transport, $email, $envelope);
+
+        $this->assertArrayHasKey('Headers', $payload);
+        $this->assertCount(1, $payload['Headers']);
+
+        $this->assertEquals(['Name' => 'foo', 'Value' => 'bar'], $payload['Headers'][0]);
+    }
+
+    public function testSend()
+    {
+        $client = new MockHttpClient(function (string $method, string $url, array $options): ResponseInterface {
+            $this->assertSame('POST', $method);
+            $this->assertSame('https://app.ohmysmtp.com/api/v1/send', $url);
+            $this->assertStringContainsStringIgnoringCase('OhMySMTP-Server-Token: KEY', $options['headers'][1] ?? $options['request_headers'][1]);
+
+            $body = json_decode($options['body'], true);
+            $this->assertSame('"Fabien" <fabpot@symfony.com>', $body['from']);
+            $this->assertSame('"Saif Eddin" <saif.gmati@symfony.com>', $body['to']);
+            $this->assertSame('Hello!', $body['subject']);
+            $this->assertSame('Hello There!', $body['textbody']);
+
+            return new MockResponse(json_encode(['id' => 'foobar', 'status' => 'pending']), [
+                'http_code' => 200,
+            ]);
+        });
+
+        $transport = new OhMySmtpApiTransport('KEY', $client);
+
+        $mail = new Email();
+        $mail->subject('Hello!')
+            ->to(new Address('saif.gmati@symfony.com', 'Saif Eddin'))
+            ->from(new Address('fabpot@symfony.com', 'Fabien'))
+            ->text('Hello There!');
+
+        $message = $transport->send($mail);
+
+        $this->assertSame('foobar', $message->getMessageId());
+    }
+
+    public function testSendThrowsForErrorResponse()
+    {
+        $client = new MockHttpClient(static function (string $method, string $url, array $options): ResponseInterface {
+            return new MockResponse(json_encode(['Message' => 'i\'m a teapot', 'ErrorCode' => 418]), [
+                'http_code' => 418,
+                'response_headers' => [
+                    'content-type' => 'application/json',
+                ],
+            ]);
+        });
+        $transport = new OhMySmtpApiTransport('KEY', $client);
+        $transport->setPort(8984);
+
+        $mail = new Email();
+        $mail->subject('Hello!')
+            ->to(new Address('saif.gmati@symfony.com', 'Saif Eddin'))
+            ->from(new Address('fabpot@symfony.com', 'Fabien'))
+            ->text('Hello There!');
+
+        $this->expectException(HttpTransportException::class);
+        $this->expectExceptionMessage('Unable to send an email: i\'m a teapot (code 418).');
+        $transport->send($mail);
+    }
+
+    public function testTagAndMetadataHeaders()
+    {
+        $email = new Email();
+        $email->getHeaders()->add(new TagHeader('password-reset'));
+        $email->getHeaders()->add(new TagHeader('2nd-tag'));
+
+        $envelope = new Envelope(new Address('alice@system.com'), [new Address('bob@system.com')]);
+
+        $transport = new OhMySmtpApiTransport('ACCESS_KEY');
+        $method = new \ReflectionMethod(OhMySmtpApiTransport::class, 'getPayload');
+        $method->setAccessible(true);
+        $payload = $method->invoke($transport, $email, $envelope);
+
+        $this->assertArrayNotHasKey('Headers', $payload);
+        $this->assertArrayHasKey('tags', $payload);
+
+        $this->assertSame(['password-reset', '2nd-tag'], $payload['tags']);
+    }
+}

src/Symfony/Component/Mailer/Bridge/OhMySmtp/Tests/Transport/OhMySmtpSmtpTransportTest.php

@@ -0,0 +1,51 @@
+<?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\Bridge\OhMySmtp\Tests\Transport;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Mailer\Bridge\OhMySmtp\Transport\OhMySmtpSmtpTransport;
+use Symfony\Component\Mailer\Header\TagHeader;
+use Symfony\Component\Mime\Email;
+
+final class OhMySmtpSmtpTransportTest extends TestCase
+{
+    public function testCustomHeader()
+    {
+        $email = new Email();
+        $email->getHeaders()->addTextHeader('foo', 'bar');
+
+        $transport = new OhMySmtpSmtpTransport('ACCESS_KEY');
+        $method = new \ReflectionMethod(OhMySmtpSmtpTransport::class, 'addOhMySmtpHeaders');
+        $method->setAccessible(true);
+        $method->invoke($transport, $email);
+
+        $this->assertCount(1, $email->getHeaders()->toArray());
+        $this->assertSame('foo: bar', $email->getHeaders()->get('FOO')->toString());
+    }
+
+    public function testTagAndMetadataHeaders()
+    {
+        $email = new Email();
+        $email->getHeaders()->addTextHeader('foo', 'bar');
+        $email->getHeaders()->add(new TagHeader('password-reset'));
+        $email->getHeaders()->add(new TagHeader('2nd-tag'));
+
+        $transport = new OhMySmtpSmtpTransport('ACCESS_KEY');
+        $method = new \ReflectionMethod(OhMySmtpSmtpTransport::class, 'addOhMySmtpHeaders');
+        $method->setAccessible(true);
+        $method->invoke($transport, $email);
+
+        $this->assertCount(2, $email->getHeaders()->toArray());
+        $this->assertSame('foo: bar', $email->getHeaders()->get('FOO')->toString());
+        $this->assertSame('X-OMS-Tags: password-reset, 2nd-tag', $email->getHeaders()->get('X-OMS-Tags')->toString());
+    }
+}

src/Symfony/Component/Mailer/Bridge/OhMySmtp/Tests/Transport/OhMySmtpTransportFactoryTest.php

@@ -0,0 +1,99 @@
+<?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\Bridge\OhMySmtp\Tests\Transport;
+
+use Symfony\Component\Mailer\Bridge\OhMySmtp\Transport\OhMySmtpApiTransport;
+use Symfony\Component\Mailer\Bridge\OhMySmtp\Transport\OhMySmtpSmtpTransport;
+use Symfony\Component\Mailer\Bridge\OhMySmtp\Transport\OhMySmtpTransportFactory;
+use Symfony\Component\Mailer\Test\TransportFactoryTestCase;
+use Symfony\Component\Mailer\Transport\Dsn;
+use Symfony\Component\Mailer\Transport\TransportFactoryInterface;
+
+final class OhMySmtpTransportFactoryTest extends TransportFactoryTestCase
+{
+    public function getFactory(): TransportFactoryInterface
+    {
+        return new OhMySmtpTransportFactory($this->getDispatcher(), $this->getClient(), $this->getLogger());
+    }
+
+    public function supportsProvider(): iterable
+    {
+        yield [
+            new Dsn('ohmysmtp+api', 'default'),
+            true,
+        ];
+
+        yield [
+            new Dsn('ohmysmtp', 'default'),
+            true,
+        ];
+
+        yield [
+            new Dsn('ohmysmtp+smtp', 'default'),
+            true,
+        ];
+
+        yield [
+            new Dsn('ohmysmtp+smtps', 'default'),
+            true,
+        ];
+
+        yield [
+            new Dsn('ohmysmtp+smtp', 'example.com'),
+            true,
+        ];
+    }
+
+    public function createProvider(): iterable
+    {
+        $dispatcher = $this->getDispatcher();
+        $logger = $this->getLogger();
+
+        yield [
+            new Dsn('ohmysmtp+api', 'default', self::USER),
+            new OhMySmtpApiTransport(self::USER, $this->getClient(), $dispatcher, $logger),
+        ];
+
+        yield [
+            new Dsn('ohmysmtp+api', 'example.com', self::USER, '', 8080),
+            (new OhMySmtpApiTransport(self::USER, $this->getClient(), $dispatcher, $logger))->setHost('example.com')->setPort(8080),
+        ];
+
+        yield [
+            new Dsn('ohmysmtp', 'default', self::USER),
+            new OhMySmtpSmtpTransport(self::USER, $dispatcher, $logger),
+        ];
+
+        yield [
+            new Dsn('ohmysmtp+smtp', 'default', self::USER),
+            new OhMySmtpSmtpTransport(self::USER, $dispatcher, $logger),
+        ];
+
+        yield [
+            new Dsn('ohmysmtp+smtps', 'default', self::USER),
+            new OhMySmtpSmtpTransport(self::USER, $dispatcher, $logger),
+        ];
+    }
+
+    public function unsupportedSchemeProvider(): iterable
+    {
+        yield [
+            new Dsn('ohmysmtp+foo', 'default', self::USER),
+            'The "ohmysmtp+foo" scheme is not supported; supported schemes for mailer "ohmysmtp" are: "ohmysmtp", "ohmysmtp+api", "ohmysmtp+smtp", "ohmysmtp+smtps".',
+        ];
+    }
+
+    public function incompleteDsnProvider(): iterable
+    {
+        yield [new Dsn('ohmysmtp+api', 'default')];
+    }
+}