Changeset 60698 for trunk

Timestamp:

09/01/2025 04:02:25 AM (6 weeks ago)

Author:

TimothyBlynJacobs

Message:

Mail: Support inline attachments.

MIME allows for referencing included attachments by their Content-ID header using the cid URL scheme. This can be used to embed images inline to the HTML message. For example, <img src="cid:logo">, will display the contents of message part with the Content-Id: <logo> header.

The wp_mail() function now supports including inline attachments through a new $embeds parameter. It accepts a map of Content-ID values to file paths. The wp_mail_embed_args filter can be used to customize the resulting PHPMailer::addEmbeddedImage method call.

Props jesin, swissspidy, chrisvendiadvertisingcom, SirLouen, mukesh27, yashjawale, iamadisingh.
Fixes #28059.

Location:

trunk

Files:

• src/wp-includes/pluggable.php (modified) (7 diffs)
• tests/phpunit/tests/pluggable/signatures.php (modified) (1 diff)
• tests/phpunit/tests/pluggable/wpMail.php (modified) (1 diff)

trunk/src/wp-includes/pluggable.php

@@ -159 +159 @@
      * be set using the {@see 'wp_mail_charset'} filter.
      *
+     * When using the `$embeds` parameter to embed images for use in HTML emails,
+     * reference the embedded file in your HTML with a `cid:` URL whose value
+     * matches the file's Content-ID. By default, the Content-ID (`cid`) used for
+     * each embedded file is the key in the embeds array, unless modified via the
+     * {@see 'wp_mail_embed_args'} filter. For example:
+     *
+     * `<img src="cid:0" alt="Logo">`
+     * `<img src="cid:my-image" alt="Image">`
+     *
+     * You may also customize the Content-ID for each file by using the
+     * {@see 'wp_mail_embed_args'} filter and setting the `cid` value.
+     *
      * @since 1.2.1
      * @since 5.5.0 is_email() is used for email validation,
      *              instead of PHPMailer's default validator.
+     * @since 6.9.0 Added $embeds parameter.
      *
      * @global PHPMailer\PHPMailer\PHPMailer $phpmailer
@@ -170 +183 @@
      * @param string|string[] $headers     Optional. Additional headers.
      * @param string|string[] $attachments Optional. Paths to files to attach.
+     * @param string|string[] $embeds      Optional. Paths to files to embed.
      * @return bool Whether the email was sent successfully.
      */
-    function wp_mail( $to, $subject, $message, $headers = '', $attachments = array() ) {
+    function wp_mail( $to, $subject, $message, $headers = '', $attachments = array(), $embeds = array() ) {
         // Compact the input, apply the filters, and extract them back out.
 
@@ -188 +202 @@
          *     @type string|string[] $headers     Additional headers.
          *     @type string|string[] $attachments Paths to files to attach.
+         *     @type string|string[] $embeds      Paths to files to embed.
          * }
          */
-        $atts = apply_filters( 'wp_mail', compact( 'to', 'subject', 'message', 'headers', 'attachments' ) );
+        $atts = apply_filters( 'wp_mail', compact( 'to', 'subject', 'message', 'headers', 'attachments', 'embeds' ) );
 
         /**
@@ -210 +225 @@
          *     @type string|string[] $headers     Additional headers.
          *     @type string|string[] $attachments Paths to files to attach.
+         *     @type string|string[] $embeds      Paths to files to embed.
          * }
          */
@@ -245 +261 @@
             $attachments = explode( "\n", str_replace( "\r\n", "\n", $attachments ) );
         }
+
+        if ( isset( $atts['embeds'] ) ) {
+            $embeds = $atts['embeds'];
+        }
+
+        if ( ! is_array( $embeds ) ) {
+            $embeds = explode( "\n", str_replace( "\r\n", "\n", $embeds ) );
+        }
+
         global $phpmailer;
 
@@ -532 +557 @@
         }
 
+        if ( ! empty( $embeds ) ) {
+            foreach ( $embeds as $key => $embed_path ) {
+                /**
+                 * Filters the arguments for PHPMailer's addEmbeddedImage() method.
+                 *
+                 * @since 6.9.0
+                 *
+                 * @param array $args {
+                 *     An array of arguments for `addEmbeddedImage()`.
+                 *     @type string $path        The path to the file.
+                 *     @type string $cid         The Content-ID of the image. Default: The key in the embeds array.
+                 *     @type string $name        The filename of the image.
+                 *     @type string $encoding    The encoding of the image. Default: 'base64'.
+                 *     @type string $type        The MIME type of the image. Default: empty string, which lets PHPMailer auto-detect.
+                 *     @type string $disposition The disposition of the image. Default: 'inline'.
+                 * }
+                 */
+                $embed_args = apply_filters(
+                    'wp_mail_embed_args',
+                    array(
+                        'path'        => $embed_path,
+                        'cid'         => (string) $key,
+                        'name'        => basename( $embed_path ),
+                        'encoding'    => 'base64',
+                        'type'        => '',
+                        'disposition' => 'inline',
+                    )
+                );
+
+                try {
+                    $phpmailer->addEmbeddedImage(
+                        $embed_args['path'],
+                        $embed_args['cid'],
+                        $embed_args['name'],
+                        $embed_args['encoding'],
+                        $embed_args['type'],
+                        $embed_args['disposition']
+                    );
+                } catch ( PHPMailer\PHPMailer\Exception $e ) {
+                    continue;
+                }
+            }
+        }
+
         /**
          * Fires after PHPMailer is initialized.
@@ -564 +633 @@
              *     @type string[] $headers     Additional headers.
              *     @type string[] $attachments Paths to files to attach.
+             *     @type string[] $embeds      Paths to files to embed.
              * }
              */

trunk/tests/phpunit/tests/pluggable/signatures.php

@@ -138 +138 @@
                 'headers'     => '',
                 'attachments' => array(),
+                'embeds'      => array(),
             ),
             'wp_authenticate'                 => array( 'username', 'password' ),

trunk/tests/phpunit/tests/pluggable/wpMail.php

@@ -555 +555 @@
         $this->assertNotSame( 'user1', $phpmailer->AltBody );
     }
+
+    /**
+     * Test that wp_mail() can send embedded images.
+     *
+     * @ticket 28059
+     * @covers ::wp_mail
+     */
+    public function test_wp_mail_can_send_embedded_images() {
+        $embeds = array(
+            'canola' => DIR_TESTDATA . '/images/canola.jpg',
+            DIR_TESTDATA . '/images/test-image-2.gif',
+            DIR_TESTDATA . '/images/avif-lossy.avif',
+        );
+
+        $message = '';
+        foreach ( $embeds as $key => $path ) {
+            $message .= '<p><img src="cid:' . $key . '" alt="" /></p>';
+        }
+
+        wp_mail(
+            'user@example.org',
+            'Embedded images test',
+            $message,
+            'Content-Type: text/html',
+            array(),
+            $embeds
+        );
+
+        $mailer      = tests_retrieve_phpmailer_instance();
+        $attachments = $mailer->getAttachments();
+
+        foreach ( $attachments as $attachment ) {
+            $inline_embed_exists = in_array( $attachment[0], $embeds, true ) && 'inline' === $attachment[6];
+            $this->assertTrue( $inline_embed_exists, 'The attachment ' . $attachment[2] . ' is not inline in the embeds array.' );
+        }
+        foreach ( $embeds as $key => $path ) {
+            $this->assertStringContainsString( 'cid:' . $key, $mailer->get_sent()->body, 'The cid ' . $key . ' is not referenced in the mail body.' );
+        }
+    }
+    /**
+     * Test that wp_mail() can send embedded images as a multiple line string.
+     *
+     * @ticket 28059
+     * @covers ::wp_mail
+     */
+    public function test_wp_mail_string_embeds() {
+        $embeds  = DIR_TESTDATA . '/images/canola.jpg' . "\n";
+        $embeds .= DIR_TESTDATA . '/images/test-image-2.gif';
+
+        $message = '<p><img src="cid:0" alt="" /></p><p><img src="cid:1" alt="" /></p>';
+
+        wp_mail(
+            'user@example.org',
+            'Embedded images test',
+            $message,
+            'Content-Type: text/html',
+            array(),
+            $embeds
+        );
+
+        $embeds_array = explode( "\n", $embeds );
+        $mailer       = tests_retrieve_phpmailer_instance();
+        $attachments  = $mailer->getAttachments();
+
+        foreach ( $attachments as $attachment ) {
+            $inline_embed_exists = in_array( $attachment[0], $embeds_array, true ) && 'inline' === $attachment[6];
+            $this->assertTrue( $inline_embed_exists, 'The attachment ' . $attachment[2] . ' is not inline in the embeds array.' );
+        }
+        foreach ( $embeds_array as $key => $path ) {
+            $this->assertStringContainsString( 'cid:' . $key, $mailer->get_sent()->body, 'The cid ' . $key . ' is not referenced in the mail body.' );
+        }
+    }
 }