Changeset 60698 for trunk/src/wp-includes/pluggable.php

Timestamp:

09/01/2025 04:02:25 AM (4 months 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.

File:

• trunk/src/wp-includes/pluggable.php (modified) (7 diffs)

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.
              * }
              */