minor #17372 Use addPart instead of embed* or attach*. (hiddewie)

javiereguiluz · javiereguiluz · commit eca311688f93 · 2022-10-20T17:21:24.000+02:00
This PR was squashed before being merged into the 6.2 branch. Discussion ---------- Use `addPart` instead of `embed*` or `attach*`. Fixes #17303 Ref #17353 Ref symfony/symfony#47711 Ref symfony/symfony#47462 This PR contains the documentation for simplifications for adding parts to `Email`s. Commits ------- ebbffc5 Use `addPart` instead of `embed*` or `attach*`.
diff --git a/mailer.rst b/mailer.rst
@@ -446,24 +446,31 @@ result of rendering some template) or PHP resources::
 File Attachments
 ~~~~~~~~~~~~~~~~
 
-Use the ``attachFromPath()`` method to attach files that exist on your file system::
+Use the ``addPart()`` method with a ``BodyFile`` to add files that exist on your file system::
 
     $email = (new Email())
         // ...
-        ->attachFromPath('/path/to/documents/terms-of-use.pdf')
+        ->addPart(new DataPart(new BodyFile('/path/to/documents/terms-of-use.pdf')))
         // optionally you can tell email clients to display a custom name for the file
-        ->attachFromPath('/path/to/documents/privacy.pdf', 'Privacy Policy')
+        ->addPart(new DataPart(new BodyFile('/path/to/documents/privacy.pdf', 'Privacy Policy')))
         // optionally you can provide an explicit MIME type (otherwise it's guessed)
-        ->attachFromPath('/path/to/documents/contract.doc', 'Contract', 'application/msword')
+        ->addPart(new DataPart(new BodyFile('/path/to/documents/contract.doc', 'Contract', 'application/msword')))
     ;
 
-Alternatively you can use the ``attach()`` method to attach contents from a stream::
+Alternatively you can attach contents from a stream by passing it directly to the ``DataPart`` ::
 
     $email = (new Email())
         // ...
-        ->attach(fopen('/path/to/documents/contract.doc', 'r'))
+        ->addPart(new DataPart(fopen('/path/to/documents/contract.doc', 'r')))
     ;
 
+.. deprecated:: 6.2
+
+    In Symfony versions previous to 6.2, the methods ``attachFromPath`` and ``attach``
+    could be used to add attachments. These methods have been deprecated and replaced with
+    ``addPart``.
+
+
 Embedding Images
 ~~~~~~~~~~~~~~~~
 
@@ -472,25 +479,27 @@ instead of adding them as attachments. When using Twig to render the email
 contents, as explained :ref:`later in this article <mailer-twig-embedding-images>`,
 the images are embedded automatically. Otherwise, you need to embed them manually.
 
-First, use the ``embed()`` or ``embedFromPath()`` method to add an image from a
+First, use the ``addPart()`` method to add an image from a
 file or stream::
 
     $email = (new Email())
         // ...
         // get the image contents from a PHP resource
-        ->embed(fopen('/path/to/images/logo.png', 'r'), 'logo', 'image/png')
+        ->addPart((new DataPart(fopen('/path/to/images/logo.png', 'r'), 'logo', 'image/png'))->asInline())
         // get the image contents from an existing file
-        ->embedFromPath('/path/to/images/signature.gif', 'footer-signature', 'image/gif')
+        ->addPart((new DataPart(new BodyFile('/path/to/images/signature.gif', 'footer-signature', 'image/gif')))->asInline())
     ;
 
+Use the ``asInline()`` method to embed the content instead of attaching it.
+
 The second optional argument of both methods is the image name ("Content-ID" in
 the MIME standard). Its value is an arbitrary string used later to reference the
 images inside the HTML contents::
 
     $email = (new Email())
         // ...
-        ->embed(fopen('/path/to/images/logo.png', 'r'), 'logo', 'image/png')
-        ->embedFromPath('/path/to/images/signature.gif', 'footer-signature', 'image/gif')
+        ->addPart((new DataPart(fopen('/path/to/images/logo.png', 'r'), 'logo', 'image/png'))->asInline())
+        ->addPart((new DataPart(new BodyFile('/path/to/images/signature.gif', 'footer-signature', 'image/gif')))->asInline())
 
         // reference images using the syntax 'cid:' + "image embed name"
         ->html('<img src="cid:logo"> ... <img src="cid:footer-signature"> ...')
@@ -503,6 +512,12 @@ images inside the HTML contents::
 
     The support of embedded images as HTML backgrounds was introduced in Symfony 6.1.
 
+.. deprecated:: 6.2
+
+    In Symfony versions previous to 6.2, the methods ``embedFromPath`` and ``embed``
+    could be used to embed images. These methods have been deprecated and replaced with
+    ``addPart`` together with inline ``DataPart``s.
+
 .. _mailer-configure-email-globally:
 
 Configuring Emails Globally
