[Mime] deprecate attach/embed methods in favor of Email::addPart()

symfony · fabpot · Oct 15, 2022 · Sep 25, 2022 · Oct 15, 2022 · 7cdbd20f6f28069c56a61636a63db0a840d52fe4
commit 7cdbd20f6f28069c56a61636a63db0a840d52fe4
diff --git a/src/Symfony/Bridge/Twig/Mime/NotificationEmail.php b/src/Symfony/Bridge/Twig/Mime/NotificationEmail.php
@@ -14,6 +14,7 @@
 use Symfony\Component\ErrorHandler\Exception\FlattenException;
 use Symfony\Component\Mime\Header\Headers;
 use Symfony\Component\Mime\Part\AbstractPart;
+use Symfony\Component\Mime\Part\DataPart;
 use Twig\Extra\CssInliner\CssInlinerExtension;
 use Twig\Extra\Inky\InkyExtension;
 use Twig\Extra\Markdown\MarkdownExtension;
@@ -134,7 +135,7 @@ public function exception(\Throwable|FlattenException $exception): static
         $exceptionAsString = $this->getExceptionAsString($exception);
 
         $this->context['exception'] = true;
-        $this->attach($exceptionAsString, 'exception.txt', 'text/plain');
+        $this->addPart(new DataPart($exceptionAsString, 'exception.txt', 'text/plain'));
         $this->importance(self::IMPORTANCE_URGENT);
 
         if (!$this->getSubject()) {

diff --git a/src/Symfony/Bridge/Twig/Mime/WrappedTemplatedEmail.php b/src/Symfony/Bridge/Twig/Mime/WrappedTemplatedEmail.php
@@ -12,6 +12,8 @@
 namespace Symfony\Bridge\Twig\Mime;
 
 use Symfony\Component\Mime\Address;
+use Symfony\Component\Mime\Part\BodyFile;
+use Symfony\Component\Mime\Part\DataPart;
 use Twig\Environment;
 
 /**
@@ -38,23 +40,17 @@ public function toName(): string
     public function image(string $image, string $contentType = null): string
     {
         $file = $this->twig->getLoader()->getSourceContext($image);
-        if ($path = $file->getPath()) {
-            $this->message->embedFromPath($path, $image, $contentType);
-        } else {
-            $this->message->embed($file->getCode(), $image, $contentType);
-        }
+        $body = $file->getPath() ? new BodyFile($file->getPath()) : $file->getCode();
+        $this->message->addPart((new DataPart($body, $image, $contentType))->asInline());
 
         return 'cid:'.$image;
     }
 
     public function attach(string $file, string $name = null, string $contentType = null): void
     {
         $file = $this->twig->getLoader()->getSourceContext($file);
-        if ($path = $file->getPath()) {
-            $this->message->attachFromPath($path, $name, $contentType);
-        } else {
-            $this->message->attach($file->getCode(), $name, $contentType);
-        }
+        $body = $file->getPath() ? new BodyFile($file->getPath()) : $file->getCode();
+        $this->message->addPart(new DataPart($body, $name, $contentType));
     }
 
     /**

diff --git a/src/Symfony/Bridge/Twig/Tests/Mime/TemplatedEmailTest.php b/src/Symfony/Bridge/Twig/Tests/Mime/TemplatedEmailTest.php
@@ -13,6 +13,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Symfony\Bridge\Twig\Mime\TemplatedEmail;
+use Symfony\Component\Mime\Part\DataPart;
 use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
 use Symfony\Component\Serializer\Encoder\JsonEncoder;
 use Symfony\Component\Serializer\Normalizer\ArrayDenormalizer;
@@ -58,7 +59,7 @@ public function testSymfonySerialize()
         $e->textTemplate('email.txt.twig');
         $e->htmlTemplate('email.html.twig');
         $e->context(['foo' => 'bar']);
-        $e->attach('Some Text file', 'test.txt');
+        $e->addPart(new DataPart('Some Text file', 'test.txt'));
         $expected = clone $e;
 
         $expectedJson = <<<EOF

diff --git a/.../Bundle/FrameworkBundle/Tests/Functional/Bundle/TestBundle/Controller/EmailController.php b/.../Bundle/FrameworkBundle/Tests/Functional/Bundle/TestBundle/Controller/EmailController.php
@@ -15,6 +15,7 @@
 use Symfony\Component\Mailer\MailerInterface;
 use Symfony\Component\Mime\Address;
 use Symfony\Component\Mime\Email;
+use Symfony\Component\Mime\Part\DataPart;
 
 class EmailController
 {
@@ -25,15 +26,15 @@ public function indexAction(MailerInterface $mailer)
             ->addCc('cc@symfony.com')
             ->text('Bar!')
             ->html('<p>Foo</p>')
-            ->attach(file_get_contents(__FILE__), 'foobar.php')
+            ->addPart(new DataPart(file_get_contents(__FILE__), 'foobar.php'))
         );
 
         $mailer->send((new Email())->to('fabien@symfony.com', 'thomas@symfony.com')->from('fabien@symfony.com')->subject('Foo')
             ->addReplyTo(new Address('me@symfony.com', 'Fabien Potencier'))
             ->addCc('cc@symfony.com')
             ->text('Bar!')
             ->html('<p>Foo</p>')
-            ->attach(file_get_contents(__FILE__), 'foobar.php')
+            ->addPart(new DataPart(file_get_contents(__FILE__), 'foobar.php'))
         );
 
         return new Response();

diff --git a/src/Symfony/Component/Mailer/Bridge/Infobip/Tests/Transport/InfobipApiTransportTest.php b/src/Symfony/Component/Mailer/Bridge/Infobip/Tests/Transport/InfobipApiTransportTest.php
@@ -19,6 +19,7 @@
 use Symfony\Component\Mailer\SentMessage;
 use Symfony\Component\Mime\Address;
 use Symfony\Component\Mime\Email;
+use Symfony\Component\Mime\Part\DataPart;
 use Symfony\Contracts\HttpClient\ResponseInterface;
 
 class InfobipApiTransportTest extends TestCase
@@ -206,8 +207,8 @@ public function testSendEmailWithAttachmentsShouldCalledInfobipWithTheRightParam
     {
         $email = $this->basicValidEmail()
             ->text('foobar')
-            ->attach('some attachment', 'attachment.txt', 'text/plain')
-            ->embed('some inline attachment', 'inline.txt', 'text/plain')
+            ->addPart(new DataPart('some attachment', 'attachment.txt', 'text/plain'))
+            ->addPart((new DataPart('some inline attachment', 'inline.txt', 'text/plain'))->asInline())
         ;
 
         $this->transport->send($email);
@@ -320,8 +321,8 @@ public function testSendEmailWithAttachmentsWithSuccess()
     {
         $email = $this->basicValidEmail()
             ->text('foobar')
-            ->attach('some attachment', 'attachment.txt', 'text/plain')
-            ->embed('some inline attachment', 'inline.txt', 'text/plain')
+            ->addPart(new DataPart('some attachment', 'attachment.txt', 'text/plain'))
+            ->addPart((new DataPart('some inline attachment', 'inline.txt', 'text/plain'))->asInline())
         ;
 
         $sentMessage = $this->transport->send($email);

diff --git a/src/Symfony/Component/Mailer/Bridge/Infobip/composer.json b/src/Symfony/Component/Mailer/Bridge/Infobip/composer.json
@@ -27,6 +27,9 @@
     "require-dev": {
         "symfony/http-client": "^6.1"
     },
+    "conflict": {
+        "symfony/mime": "<6.2"
+    },
     "autoload": {
         "psr-4": {
             "Symfony\\Component\\Mailer\\Bridge\\Infobip\\": ""

diff --git a/src/Symfony/Component/Mailer/Bridge/Sendgrid/Tests/Transport/SendgridApiTransportTest.php b/src/Symfony/Component/Mailer/Bridge/Sendgrid/Tests/Transport/SendgridApiTransportTest.php
@@ -18,6 +18,7 @@
 use Symfony\Component\Mailer\Header\TagHeader;
 use Symfony\Component\Mime\Address;
 use Symfony\Component\Mime\Email;
+use Symfony\Component\Mime\Part\DataPart;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 use Symfony\Contracts\HttpClient\ResponseInterface;
 
@@ -107,7 +108,7 @@ public function testLineBreaksInEncodedAttachment()
         $email->from('foo@example.com')
             ->to('bar@example.com')
             // even if content doesn't include new lines, the base64 encoding performed later may add them
-            ->attach('Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod', 'lorem.txt');
+            ->addPart(new DataPart('Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod', 'lorem.txt'));
 
         $response = $this->createMock(ResponseInterface::class);
 

diff --git a/src/Symfony/Component/Mailer/Bridge/Sendgrid/composer.json b/src/Symfony/Component/Mailer/Bridge/Sendgrid/composer.json
@@ -22,6 +22,9 @@
     "require-dev": {
         "symfony/http-client": "^5.4|^6.0"
     },
+    "conflict": {
+        "symfony/mime": "<6.2"
+    },
     "autoload": {
         "psr-4": { "Symfony\\Component\\Mailer\\Bridge\\Sendgrid\\": "" },
         "exclude-from-classmap": [

diff --git a/...Symfony/Component/Mailer/Bridge/Sendinblue/Tests/Transport/SendinblueApiTransportTest.php b/...Symfony/Component/Mailer/Bridge/Sendinblue/Tests/Transport/SendinblueApiTransportTest.php
@@ -130,7 +130,6 @@ public function testSend()
         $transport = new SendinblueApiTransport('ACCESS_KEY', $client);
         $transport->setPort(8984);
 
-        $dataPart = new DataPart('body');
         $mail = new Email();
         $mail->subject('Hello!')
             ->to(new Address('saif.gmati@symfony.com', 'Saif Eddin'))
@@ -140,7 +139,7 @@ public function testSend()
             ->addCc('foo@bar.fr')
             ->addBcc('foo@bar.fr')
             ->addReplyTo('foo@bar.fr')
-            ->attachPart($dataPart)
+            ->addPart(new DataPart('body'))
         ;
 
         $message = $transport->send($mail);

diff --git a/src/Symfony/Component/Mailer/Bridge/Sendinblue/composer.json b/src/Symfony/Component/Mailer/Bridge/Sendinblue/composer.json
@@ -22,6 +22,9 @@
     "require-dev": {
         "symfony/http-client": "^5.4|^6.0"
     },
+    "conflict": {
+        "symfony/mime": "<6.2"
+    },
     "autoload": {
         "psr-4": { "Symfony\\Component\\Mailer\\Bridge\\Sendinblue\\": "" },
         "exclude-from-classmap": [

diff --git a/src/Symfony/Component/Mailer/Tests/Transport/Smtp/SmtpTransportTest.php b/src/Symfony/Component/Mailer/Tests/Transport/Smtp/SmtpTransportTest.php
@@ -21,6 +21,8 @@
 use Symfony\Component\Mime\Address;
 use Symfony\Component\Mime\Email;
 use Symfony\Component\Mime\Exception\InvalidArgumentException;
+use Symfony\Component\Mime\Part\BodyFile;
+use Symfony\Component\Mime\Part\DataPart;
 use Symfony\Component\Mime\RawMessage;
 
 /**
@@ -103,7 +105,7 @@ public function testSendInvalidMessage()
         $message = new Email();
         $message->to('recipient@example.org');
         $message->from('sender@example.org');
-        $message->attachFromPath('/does_not_exists');
+        $message->addPart(new DataPart(new BodyFile('/does_not_exists')));
 
         try {
             $transport->send($message);

diff --git a/src/Symfony/Component/Mailer/composer.json b/src/Symfony/Component/Mailer/composer.json
@@ -31,7 +31,8 @@
     },
     "conflict": {
         "symfony/http-kernel": "<5.4",
-        "symfony/messenger": "<6.2"
+        "symfony/messenger": "<6.2",
+        "symfony/mime": "<6.2"
     },
     "autoload": {
         "psr-4": { "Symfony\\Component\\Mailer\\": "" },

diff --git a/src/Symfony/Component/Mime/Email.php b/src/Symfony/Component/Mime/Email.php
@@ -327,15 +327,15 @@ public function getHtmlCharset(): ?string
      */
     public function attach($body, string $name = null, string $contentType = null): static
     {
-        return $this->attachPart(new DataPart($body, $name, $contentType));
+        return $this->addPart(new DataPart($body, $name, $contentType));
     }
 
     /**
      * @return $this
      */
     public function attachFromPath(string $path, string $name = null, string $contentType = null): static
     {
-        return $this->attachPart(new DataPart(new BodyFile($path), $name, $contentType));
+        return $this->addPart(new DataPart(new BodyFile($path), $name, $contentType));
     }
 
     /**
@@ -345,21 +345,33 @@ public function attachFromPath(string $path, string $name = null, string $conten
      */
     public function embed($body, string $name = null, string $contentType = null): static
     {
-        return $this->attachPart((new DataPart($body, $name, $contentType))->asInline());
+        return $this->addPart((new DataPart($body, $name, $contentType))->asInline());
     }
 
     /**
      * @return $this
      */
     public function embedFromPath(string $path, string $name = null, string $contentType = null): static
     {
-        return $this->attachPart((new DataPart(new BodyFile($path), $name, $contentType))->asInline());
+        return $this->addPart((new DataPart(new BodyFile($path), $name, $contentType))->asInline());
     }
 
     /**
      * @return $this
+     *
+     * @deprecated since Symfony 6.2, use addPart() instead
      */
     public function attachPart(DataPart $part): static
+    {
+        @trigger_deprecation('symfony/mime', '6.2', 'The "%s()" method is deprecated, use "addPart()" instead.', __METHOD__);
+
+        return $this->addPart($part);
+    }
+
+    /**
+     * @return $this
+     */
+    public function addPart(DataPart $part): static
     {
         $this->cachedBody = null;
         $this->attachments[] = $part;

diff --git a/src/Symfony/Component/Mime/MessageConverter.php b/src/Symfony/Component/Mime/MessageConverter.php
@@ -58,7 +58,7 @@ public static function toEmail(Message $message): Email
                 throw new RuntimeException(sprintf('Unable to create an Email from an instance of "%s" as the body is too complex.', get_debug_type($message)));
             }
 
-            return self::attachParts($email, \array_slice($parts, 1));
+            return self::addParts($email, \array_slice($parts, 1));
         }
 
         throw new RuntimeException(sprintf('Unable to create an Email from an instance of "%s" as the body is too complex.', get_debug_type($message)));
@@ -104,17 +104,17 @@ private static function createEmailFromRelatedPart(Message $message, RelatedPart
             throw new RuntimeException(sprintf('Unable to create an Email from an instance of "%s" as the body is too complex.', get_debug_type($message)));
         }
 
-        return self::attachParts($email, \array_slice($parts, 1));
+        return self::addParts($email, \array_slice($parts, 1));
     }
 
-    private static function attachParts(Email $email, array $parts): Email
+    private static function addParts(Email $email, array $parts): Email
     {
         foreach ($parts as $part) {
             if (!$part instanceof DataPart) {
                 throw new RuntimeException(sprintf('Unable to create an Email from an instance of "%s" as the body is too complex.', get_debug_type($email)));
             }
 
-            $email->attachPart($part);
+            $email->addPart($part);
         }
 
         return $email;

diff --git a/src/Symfony/Component/Mime/Tests/Crypto/SMimeSignerTest.php b/src/Symfony/Component/Mime/Tests/Crypto/SMimeSignerTest.php
@@ -16,6 +16,7 @@
 use Symfony\Component\Mime\Email;
 use Symfony\Component\Mime\Header\Headers;
 use Symfony\Component\Mime\Message;
+use Symfony\Component\Mime\Part\DataPart;
 use Symfony\Component\Mime\Part\TextPart;
 
 /**
@@ -120,8 +121,8 @@ public function testSignedMessageWithAttachments()
         );
         $message->html('html content <img src="cid:test.gif">');
         $message->text('text content');
-        $message->attach(fopen(__DIR__.'/../Fixtures/mimetypes/test', 'r'));
-        $message->attach(fopen(__DIR__.'/../Fixtures/mimetypes/test.gif', 'r'), 'test.gif');
+        $message->addPart(new DataPart(fopen(__DIR__.'/../Fixtures/mimetypes/test', 'r')));
+        $message->addPart(new DataPart(fopen(__DIR__.'/../Fixtures/mimetypes/test.gif', 'r'), 'test.gif'));
 
         $signer = new SMimeSigner($this->samplesDir.'sign.crt', $this->samplesDir.'sign.key');