feature #58361 [Mailer][Mime] Support unicode email addresses (arnt, OskarStark)

This PR was merged into the 7.2 branch.

Discussion
----------

[Mailer][Mime] Support unicode email addresses

| Q             | A
| ------------- | ---
| Branch?       | 7.2
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| License       | MIT

This allows applications to send mail to all-Chinese email addresses, or like my test address grå`@gr`å.org. Code that uses Symfony needs no change and should experience no difference, although if the upstream MTA doesn't support it (most do by now) then an exception is thrown slightly later than before this change.

Commits
-------

b1deef8ff3 Reinstate the restriction that the sender's localpart must be all-ASCII.
c11d6e068d Code style conformance and dependency updates.
3fbbb235d6 Resolve code review comments from stof and oska
8597c1ee8d Update src/Symfony/Component/Mime/Address.php
2d74b98061 Fix minor spelling error.
6f07a17bbf Send SMTPUTF8 if the message needs it and the server supports it.
d43b8329f2 Add new accessors to help determine whether to use the SMTPUTF8 extension

Author: fabpot

CHANGELOG.md

@@ -10,6 +10,7 @@ CHANGELOG
    you now need to use the `IncompleteDsnTestTrait`.
 
  * Make `TransportFactoryTestCase` compatible with PHPUnit 10+
+ * Support unicode email addresses such as "dømi@dømi.fo"
 
 7.1
 ---

Envelope.php

@@ -85,4 +85,33 @@ public function getRecipients(): array
     {
         return $this->recipients;
     }
+
+    /**
+     * Returns true if any address' localpart contains at least one
+     * non-ASCII character, and false if all addresses have all-ASCII
+     * localparts.
+     *
+     * This helps to decide whether to the SMTPUTF8 extensions (RFC
+     * 6530 and following) for any given message.
+     *
+     * The SMTPUTF8 extension is strictly required if any address
+     * contains a non-ASCII character in its localpart. If non-ASCII
+     * is only used in domains (e.g. horst@freiherr-von-mühlhausen.de)
+     * then it is possible to to send the message using IDN encoding
+     * instead of SMTPUTF8. The most common software will display the
+     * message as intended.
+     */
+    public function anyAddressHasUnicodeLocalpart(): bool
+    {
+        if ($this->getSender()->hasUnicodeLocalpart()) {
+            return true;
+        }
+        foreach ($this->getRecipients() as $r) {
+            if ($r->hasUnicodeLocalpart()) {
+                return true;
+            }
+        }
+
+        return false;
+    }
 }

Tests/EnvelopeTest.php

@@ -98,7 +98,7 @@ public function testSenderFromHeadersWithoutFrom()
         $this->assertEquals($from, $e->getSender());
     }
 
-    public function testSenderFromHeadersWithMulitpleHeaders()
+    public function testSenderFromHeadersWithMultipleHeaders()
     {
         $headers = new Headers();
         $headers->addMailboxListHeader('From', [new Address('[email protected]', 'from'), '[email protected]']);
@@ -127,6 +127,19 @@ public function testRecipientsFromHeaders()
         $this->assertEquals([new Address('[email protected]'), new Address('[email protected]'), new Address('[email protected]')], $e->getRecipients());
     }
 
+    public function testUnicodeLocalparts()
+    {
+        /* dømi means example and is reserved by the .fo registry */
+        $i = new Address('info@dømi.fo');
+        $d = new Address('dømi@dømi.fo');
+        $e = new Envelope($i, [$i]);
+        $this->assertFalse($e->anyAddressHasUnicodeLocalpart());
+        $e = new Envelope($i, [$d]);
+        $this->assertTrue($e->anyAddressHasUnicodeLocalpart());
+        $e = new Envelope($i, [$i, $d]);
+        $this->assertTrue($e->anyAddressHasUnicodeLocalpart());
+    }
+
     public function testRecipientsFromHeadersWithNames()
     {
         $headers = new Headers();

Tests/Transport/Smtp/EsmtpTransportTest.php

@@ -12,6 +12,7 @@
 namespace Symfony\Component\Mailer\Tests\Transport\Smtp;
 
 use PHPUnit\Framework\TestCase;
+use Symfony\Component\Mailer\Exception\InvalidArgumentException;
 use Symfony\Component\Mailer\Exception\TransportException;
 use Symfony\Component\Mailer\Transport\Smtp\Auth\CramMd5Authenticator;
 use Symfony\Component\Mailer\Transport\Smtp\Auth\LoginAuthenticator;
@@ -62,6 +63,53 @@ public function testExtensibility()
         $this->assertContains("RCPT TO:<[email protected]> NOTIFY=FAILURE\r\n", $stream->getCommands());
     }
 
+    public function testSmtpUtf8()
+    {
+        $stream = new DummyStream();
+        $transport = new SmtpUtf8EsmtpTransport(stream: $stream);
+
+        $message = new Email();
+        $message->from('info@dømi.fo');
+        $message->addTo('dømi@dømi.fo');
+        $message->text('.');
+
+        $transport->send($message);
+
+        $this->assertContains("MAIL FROM:<[email protected]> SMTPUTF8\r\n", $stream->getCommands());
+        $this->assertContains("RCPT TO:<dø[email protected]>\r\n", $stream->getCommands());
+    }
+
+    public function testMissingSmtpUtf8()
+    {
+        $stream = new DummyStream();
+        $transport = new EsmtpTransport(stream: $stream);
+
+        $message = new Email();
+        $message->from('info@dømi.fo');
+        $message->addTo('dømi@dømi.fo');
+        $message->text('.');
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Invalid addresses: non-ASCII characters not supported in local-part of email.');
+        $transport->send($message);
+    }
+
+    public function testSmtpUtf8FallbackToIDN()
+    {
+        $stream = new DummyStream();
+        $transport = new EsmtpTransport(stream: $stream);
+
+        $message = new Email();
+        $message->from('info@dømi.fo'); // UTF8 only in the domain
+        $message->addTo('[email protected]');
+        $message->text('.');
+
+        $transport->send($message);
+
+        $this->assertContains("MAIL FROM:<[email protected]>\r\n", $stream->getCommands());
+        $this->assertContains("RCPT TO:<[email protected]>\r\n", $stream->getCommands());
+    }
+
     public function testConstructorWithDefaultAuthenticators()
     {
         $stream = new DummyStream();
@@ -270,3 +318,17 @@ public function executeCommand(string $command, array $codes): string
         return $response;
     }
 }
+
+class SmtpUtf8EsmtpTransport extends EsmtpTransport
+{
+    public function executeCommand(string $command, array $codes): string
+    {
+        $response = parent::executeCommand($command, $codes);
+
+        if (str_starts_with($command, 'EHLO ')) {
+            $response .= "250 SMTPUTF8\r\n";
+        }
+
+        return $response;
+    }
+}

Transport/Smtp/EsmtpTransport.php

@@ -195,6 +195,11 @@ private function parseCapabilities(string $ehloResponse): array
         return $capabilities;
     }
 
+    protected function serverSupportsSmtpUtf8(): bool
+    {
+        return \array_key_exists('SMTPUTF8', $this->capabilities);
+    }
+
     private function handleAuth(array $modes): void
     {
         if (!$this->username) {

Transport/Smtp/SmtpTransport.php

@@ -14,6 +14,7 @@
 use Psr\EventDispatcher\EventDispatcherInterface;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\Mailer\Envelope;
+use Symfony\Component\Mailer\Exception\InvalidArgumentException;
 use Symfony\Component\Mailer\Exception\LogicException;
 use Symfony\Component\Mailer\Exception\TransportException;
 use Symfony\Component\Mailer\Exception\TransportExceptionInterface;
@@ -211,7 +212,7 @@ protected function doSend(SentMessage $message): void
 
         try {
             $envelope = $message->getEnvelope();
-            $this->doMailFromCommand($envelope->getSender()->getEncodedAddress());
+            $this->doMailFromCommand($envelope->getSender()->getEncodedAddress(), $envelope->anyAddressHasUnicodeLocalpart());
             foreach ($envelope->getRecipients() as $recipient) {
                 $this->doRcptToCommand($recipient->getEncodedAddress());
             }
@@ -244,14 +245,22 @@ protected function doSend(SentMessage $message): void
         }
     }
 
+    protected function serverSupportsSmtpUtf8(): bool
+    {
+        return false;
+    }
+
     private function doHeloCommand(): void
     {
         $this->executeCommand(\sprintf("HELO %s\r\n", $this->domain), [250]);
     }
 
-    private function doMailFromCommand(string $address): void
+    private function doMailFromCommand(string $address, bool $smtputf8): void
     {
-        $this->executeCommand(\sprintf("MAIL FROM:<%s>\r\n", $address), [250]);
+        if ($smtputf8 && !$this->serverSupportsSmtpUtf8()) {
+            throw new InvalidArgumentException('Invalid addresses: non-ASCII characters not supported in local-part of email.');
+        }
+        $this->executeCommand(\sprintf("MAIL FROM:<%s>%s\r\n", $address, $smtputf8 ? ' SMTPUTF8' : ''), [250]);
     }
 
     private function doRcptToCommand(string $address): void

composer.json

@@ -21,7 +21,7 @@
         "psr/event-dispatcher": "^1",
         "psr/log": "^1|^2|^3",
         "symfony/event-dispatcher": "^6.4|^7.0",
-        "symfony/mime": "^6.4|^7.0",
+        "symfony/mime": "^7.2",
         "symfony/service-contracts": "^2.5|^3"
     },
     "require-dev": {