feature #33270 [Mime] Remove NamedAddress (fabpot)

This PR was merged into the 4.4 branch.

Discussion
----------

[Mime] Remove NamedAddress

| Q             | A
| ------------- | ---
| Branch?       | 4.4
| Bug fix?      | no
| New feature?  | no <!-- please update src/**/CHANGELOG.md files -->
| BC breaks?    | yes     <!-- 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

While working on #33091, we realize that having both `NamedAddress` and `Address` brings some unneeded complexity. Initially, I added both as some headers do not support `NamedAddress`es. But the code already does the right thing by "downgrading" them to `Address` instances. So, let's simplify our internal code and make life easier for our users too.

Commits
-------

eb7d74e [Mime] Remove NamedAddress

UPGRADE-4.4.md

@@ -157,6 +157,11 @@ Messenger
  * Deprecated passing a `ContainerInterface` instance as first argument of the `ConsumeMessagesCommand` constructor,
    pass a `RoutableMessageBus`  instance instead.
 
+Mime
+----
+
+ * Removed `NamedAddress`, use `Address` instead (which supports a name now)
+
 MonologBridge
 --------------
 

src/Symfony/Bridge/Twig/Mime/WrappedTemplatedEmail.php

@@ -12,7 +12,6 @@
 namespace Symfony\Bridge\Twig\Mime;
 
 use Symfony\Component\Mime\Address;
-use Symfony\Component\Mime\NamedAddress;
 use Twig\Environment;
 
 /**
@@ -33,9 +32,7 @@ public function __construct(Environment $twig, TemplatedEmail $message)
 
     public function toName(): string
     {
-        $to = $this->message->getTo()[0];
-
-        return $to instanceof NamedAddress ? $to->getName() : '';
+        return $this->message->getTo()[0]->getName();
     }
 
     public function image(string $image, string $contentType = null): string
@@ -93,15 +90,15 @@ public function getReturnPath(): string
     /**
      * @return $this
      */
-    public function addFrom(string $address, string $name = null): self
+    public function addFrom(string $address, string $name = ''): self
     {
-        $this->message->addFrom($name ? new NamedAddress($address, $name) : new Address($address));
+        $this->message->addFrom(new Address($address, $name));
 
         return $this;
     }
 
     /**
-     * @return (Address|NamedAddress)[]
+     * @return Address[]
      */
     public function getFrom(): array
     {
@@ -129,15 +126,15 @@ public function getReplyTo(): array
     /**
      * @return $this
      */
-    public function addTo(string $address, string $name = null): self
+    public function addTo(string $address, string $name = ''): self
     {
-        $this->message->addTo($name ? new NamedAddress($address, $name) : new Address($address));
+        $this->message->addTo(new Address($address, $name));
 
         return $this;
     }
 
     /**
-     * @return (Address|NamedAddress)[]
+     * @return Address[]
      */
     public function getTo(): array
     {
@@ -147,15 +144,15 @@ public function getTo(): array
     /**
      * @return $this
      */
-    public function addCc(string $address, string $name = null): self
+    public function addCc(string $address, string $name = ''): self
     {
-        $this->message->addCc($name ? new NamedAddress($address, $name) : new Address($address));
+        $this->message->addCc(new Address($address, $name));
 
         return $this;
     }
 
     /**
-     * @return (Address|NamedAddress)[]
+     * @return Address[]
      */
     public function getCc(): array
     {
@@ -165,15 +162,15 @@ public function getCc(): array
     /**
      * @return $this
      */
-    public function addBcc(string $address, string $name = null): self
+    public function addBcc(string $address, string $name = ''): self
     {
-        $this->message->addBcc($name ? new NamedAddress($address, $name) : new Address($address));
+        $this->message->addBcc(new Address($address, $name));
 
         return $this;
     }
 
     /**
-     * @return (Address|NamedAddress)[]
+     * @return Address[]
      */
     public function getBcc(): array
     {

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/Bundle/TestBundle/Controller/EmailController.php

@@ -13,8 +13,8 @@
 
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\Mailer\MailerInterface;
+use Symfony\Component\Mime\Address;
 use Symfony\Component\Mime\Email;
-use Symfony\Component\Mime\NamedAddress;
 
 class EmailController
 {
@@ -29,7 +29,7 @@ public function indexAction(MailerInterface $mailer)
         );
 
         $mailer->send((new Email())->to('fabien@symfony.com', 'thomas@symfony.com')->from('fabien@symfony.com')->subject('Foo')
-            ->addReplyTo(new NamedAddress('me@symfony.com', 'Fabien Potencier'))
+            ->addReplyTo(new Address('me@symfony.com', 'Fabien Potencier'))
             ->addCc('cc@symfony.com')
             ->text('Bar!')
             ->html('<p>Foo</p>')

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

@@ -16,7 +16,6 @@
 use Symfony\Component\Mime\Address;
 use Symfony\Component\Mime\Header\Headers;
 use Symfony\Component\Mime\Message;
-use Symfony\Component\Mime\NamedAddress;
 
 class SmtpEnvelopeTest extends TestCase
 {
@@ -28,13 +27,13 @@ public function testConstructorWithAddressSender()
 
     public function testConstructorWithNamedAddressSender()
     {
-        $e = new SmtpEnvelope(new NamedAddress('fabien@symfony.com', 'Fabien'), [new Address('thomas@symfony.com')]);
+        $e = new SmtpEnvelope(new Address('fabien@symfony.com', 'Fabien'), [new Address('thomas@symfony.com')]);
         $this->assertEquals(new Address('fabien@symfony.com'), $e->getSender());
     }
 
     public function testConstructorWithAddressRecipients()
     {
-        $e = new SmtpEnvelope(new Address('fabien@symfony.com'), [new Address('thomas@symfony.com'), new NamedAddress('lucas@symfony.com', 'Lucas')]);
+        $e = new SmtpEnvelope(new Address('fabien@symfony.com'), [new Address('thomas@symfony.com'), new Address('lucas@symfony.com', 'Lucas')]);
         $this->assertEquals([new Address('thomas@symfony.com'), new Address('lucas@symfony.com')], $e->getRecipients());
     }
 
@@ -53,19 +52,19 @@ public function testConstructorWithWrongRecipients()
     public function testSenderFromHeaders()
     {
         $headers = new Headers();
-        $headers->addPathHeader('Return-Path', new NamedAddress('return@symfony.com', 'return'));
+        $headers->addPathHeader('Return-Path', new Address('return@symfony.com', 'return'));
         $headers->addMailboxListHeader('To', ['from@symfony.com']);
         $e = SmtpEnvelope::create(new Message($headers));
         $this->assertEquals('return@symfony.com', $e->getSender()->getAddress());
 
         $headers = new Headers();
-        $headers->addMailboxHeader('Sender', new NamedAddress('sender@symfony.com', 'sender'));
+        $headers->addMailboxHeader('Sender', new Address('sender@symfony.com', 'sender'));
         $headers->addMailboxListHeader('To', ['from@symfony.com']);
         $e = SmtpEnvelope::create(new Message($headers));
         $this->assertEquals('sender@symfony.com', $e->getSender()->getAddress());
 
         $headers = new Headers();
-        $headers->addMailboxListHeader('From', [new NamedAddress('from@symfony.com', 'from'), 'some@symfony.com']);
+        $headers->addMailboxListHeader('From', [new Address('from@symfony.com', 'from'), 'some@symfony.com']);
         $headers->addMailboxListHeader('To', ['from@symfony.com']);
         $e = SmtpEnvelope::create(new Message($headers));
         $this->assertEquals('from@symfony.com', $e->getSender()->getAddress());
@@ -76,17 +75,17 @@ public function testSenderFromHeadersWithoutFrom()
         $headers = new Headers();
         $headers->addMailboxListHeader('To', ['from@symfony.com']);
         $e = SmtpEnvelope::create($message = new Message($headers));
-        $message->getHeaders()->addMailboxListHeader('From', [new NamedAddress('from@symfony.com', 'from')]);
+        $message->getHeaders()->addMailboxListHeader('From', [new Address('from@symfony.com', 'from')]);
         $this->assertEquals('from@symfony.com', $e->getSender()->getAddress());
     }
 
     public function testRecipientsFromHeaders()
     {
         $headers = new Headers();
         $headers->addPathHeader('Return-Path', 'return@symfony.com');
-        $headers->addMailboxListHeader('To', [new NamedAddress('to@symfony.com', 'to')]);
-        $headers->addMailboxListHeader('Cc', [new NamedAddress('cc@symfony.com', 'cc')]);
-        $headers->addMailboxListHeader('Bcc', [new NamedAddress('bcc@symfony.com', 'bcc')]);
+        $headers->addMailboxListHeader('To', [new Address('to@symfony.com', 'to')]);
+        $headers->addMailboxListHeader('Cc', [new Address('cc@symfony.com', 'cc')]);
+        $headers->addMailboxListHeader('Bcc', [new Address('bcc@symfony.com', 'bcc')]);
         $e = SmtpEnvelope::create(new Message($headers));
         $this->assertEquals([new Address('to@symfony.com'), new Address('cc@symfony.com'), new Address('bcc@symfony.com')], $e->getRecipients());
     }

src/Symfony/Component/Mime/Address.php

@@ -21,14 +21,15 @@
 /**
  * @author Fabien Potencier <fabien@symfony.com>
  */
-class Address
+final class Address
 {
     private static $validator;
     private static $encoder;
 
     private $address;
+    private $name;
 
-    public function __construct(string $address)
+    public function __construct(string $address, string $name = '')
     {
         if (!class_exists(EmailValidator::class)) {
             throw new LogicException(sprintf('The "%s" class cannot be used as it needs "%s"; try running "composer require egulias/email-validator".', __CLASS__, EmailValidator::class));
@@ -43,13 +44,19 @@ public function __construct(string $address)
         }
 
         $this->address = $address;
+        $this->name = $name;
     }
 
     public function getAddress(): string
     {
         return $this->address;
     }
 
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
     public function getEncodedAddress(): string
     {
         if (null === self::$encoder) {
@@ -61,7 +68,7 @@ public function getEncodedAddress(): string
 
     public function toString(): string
     {
-        return $this->getEncodedAddress();
+        return ($n = $this->getName()) ? $n.' <'.$this->getEncodedAddress().'>' : $this->getEncodedAddress();
     }
 
     /**

src/Symfony/Component/Mime/CHANGELOG.md

@@ -4,6 +4,7 @@ CHANGELOG
 4.4.0
 -----
 
+ * [BC BREAK] Removed `NamedAddress` (`Address` now supports a name)
  * Added PHPUnit constraints
  * Added `AbstractPart::asDebugString()`
 

src/Symfony/Component/Mime/Email.php

@@ -101,7 +101,7 @@ public function getSender(): ?Address
     }
 
     /**
-     * @param Address|NamedAddress|string ...$addresses
+     * @param Address|string ...$addresses
      *
      * @return $this
      */
@@ -111,7 +111,7 @@ public function addFrom(...$addresses)
     }
 
     /**
-     * @param Address|NamedAddress|string ...$addresses
+     * @param Address|string ...$addresses
      *
      * @return $this
      */
@@ -121,7 +121,7 @@ public function from(...$addresses)
     }
 
     /**
-     * @return (Address|NamedAddress)[]
+     * @return Address[]
      */
     public function getFrom(): array
     {
@@ -157,7 +157,7 @@ public function getReplyTo(): array
     }
 
     /**
-     * @param Address|NamedAddress|string ...$addresses
+     * @param Address|string ...$addresses
      *
      * @return $this
      */
@@ -167,7 +167,7 @@ public function addTo(...$addresses)
     }
 
     /**
-     * @param Address|NamedAddress|string ...$addresses
+     * @param Address|string ...$addresses
      *
      * @return $this
      */
@@ -177,15 +177,15 @@ public function to(...$addresses)
     }
 
     /**
-     * @return (Address|NamedAddress)[]
+     * @return Address[]
      */
     public function getTo(): array
     {
         return $this->getHeaders()->getHeaderBody('To') ?: [];
     }
 
     /**
-     * @param Address|NamedAddress|string ...$addresses
+     * @param Address|string ...$addresses
      *
      * @return $this
      */
@@ -205,15 +205,15 @@ public function cc(...$addresses)
     }
 
     /**
-     * @return (Address|NamedAddress)[]
+     * @return Address[]
      */
     public function getCc(): array
     {
         return $this->getHeaders()->getHeaderBody('Cc') ?: [];
     }
 
     /**
-     * @param Address|NamedAddress|string ...$addresses
+     * @param Address|string ...$addresses
      *
      * @return $this
      */
@@ -233,7 +233,7 @@ public function bcc(...$addresses)
     }
 
     /**
-     * @return (Address|NamedAddress)[]
+     * @return Address[]
      */
     public function getBcc(): array
     {
@@ -524,10 +524,10 @@ private function setHeaderBody(string $type, string $name, $body)
 
     private function addListAddressHeaderBody(string $name, array $addresses)
     {
-        if (!$to = $this->getHeaders()->get($name)) {
+        if (!$header = $this->getHeaders()->get($name)) {
             return $this->setListAddressHeaderBody($name, $addresses);
         }
-        $to->addAddresses(Address::createArray($addresses));
+        $header->addAddresses(Address::createArray($addresses));
 
         return $this;
     }
@@ -536,8 +536,8 @@ private function setListAddressHeaderBody(string $name, array $addresses)
     {
         $addresses = Address::createArray($addresses);
         $headers = $this->getHeaders();
-        if ($to = $headers->get($name)) {
-            $to->setAddresses($addresses);
+        if ($header = $headers->get($name)) {
+            $header->setAddresses($addresses);
         } else {
             $headers->addMailboxListHeader($name, $addresses);
         }

src/Symfony/Component/Mime/Header/Headers.php

@@ -13,7 +13,6 @@
 
 use Symfony\Component\Mime\Address;
 use Symfony\Component\Mime\Exception\LogicException;
-use Symfony\Component\Mime\NamedAddress;
 
 /**
  * A collection of headers.
@@ -60,7 +59,7 @@ public function getMaxLineLength(): int
     }
 
     /**
-     * @param (NamedAddress|Address|string)[] $addresses
+     * @param (Address|string)[] $addresses
      *
      * @return $this
      */
@@ -70,7 +69,7 @@ public function addMailboxListHeader(string $name, array $addresses): self
     }
 
     /**
-     * @param NamedAddress|Address|string $address
+     * @param Address|string $address
      *
      * @return $this
      */