Changeset 49844

Timestamp:

12/20/2020 03:07:23 PM (4 years ago)

Author:

johnbillion

Message:

Mail: Introduce a pre_wp_mail filter to allow short-circuiting the wp_mail() function without having to override the pluggable function.

Props DvanKooten, swissspidy, SergeyBiryukov, jtsternberg, ericlewis, Mte90, birgire, ayeshrajans

Fixes #35069

Location:

trunk

Files:

• src/wp-includes/pluggable.php (modified) (2 diffs)
• tests/phpunit/tests/mail.php (modified) (1 diff)

trunk/src/wp-includes/pluggable.php

@@ -162 +162 @@
      * @global PHPMailer\PHPMailer\PHPMailer $phpmailer
      *
-     * @param string|array $to          Array or comma-separated list of email addresses to send message.
-     * @param string       $subject     Email subject
-     * @param string       $message     Message contents
-     * @param string|array $headers     Optional. Additional headers.
-     * @param string|array $attachments Optional. Paths to files to attach.
-     * @return bool Whether the email contents were sent successfully.
+     * @param string|string[] $to          Array or comma-separated list of email addresses to send message.
+     * @param string          $subject     Email subject.
+     * @param string          $message     Message contents.
+     * @param string|string[] $headers     Optional. Additional headers.
+     * @param string|string[] $attachments Optional. Paths to files to attach.
+     * @return bool Whether the email was sent successfully.
      */
     function wp_mail( $to, $subject, $message, $headers = '', $attachments = array() ) {
@@ -188 +188 @@
          */
         $atts = apply_filters( 'wp_mail', compact( 'to', 'subject', 'message', 'headers', 'attachments' ) );
+
+        /**
+         * Filters whether to preempt sending an email.
+         *
+         * Returning a non-null value will short-circuit {@see wp_mail()}, returning
+         * that value instead. A boolean return value should be used to indicate whether
+         * the email was successfully sent.
+         *
+         * @since 5.7.0
+         *
+         * @param null|bool $return Short-circuit return value.
+         * @param array     $atts {
+         *     Array of the `wp_mail()` arguments.
+         *
+         *     @type string|string[] $to          Array or comma-separated list of email addresses to send message.
+         *     @type string          $subject     Email subject.
+         *     @type string          $message     Message contents.
+         *     @type string|string[] $headers     Additional headers.
+         *     @type string|string[] $attachments Paths to files to attach.
+         * }
+         */
+        $pre_wp_mail = apply_filters( 'pre_wp_mail', null, $atts );
+
+        if ( null !== $pre_wp_mail ) {
+            return $pre_wp_mail;
+        }
 
         if ( isset( $atts['to'] ) ) {

trunk/tests/phpunit/tests/mail.php

@@ -416 +416 @@
         $this->assertTrue( $phpmailer->validateAddress( 'foo@192.168.1.1' ), 'Assert PHPMailer accepts IP address email addresses' );
     }
+
+    /**
+     * Test for short-circuiting wp_mail().
+     *
+     * @ticket 35069
+     */
+    public function test_wp_mail_can_be_shortcircuited() {
+        $result1 = wp_mail( WP_TESTS_EMAIL, 'Foo', 'Bar' );
+
+        add_filter( 'pre_wp_mail', '__return_false' );
+        $result2 = wp_mail( WP_TESTS_EMAIL, 'Foo', 'Bar' );
+        remove_filter( 'pre_wp_mail', '__return_false' );
+
+        $this->assertTrue( $result1 );
+        $this->assertFalse( $result2 );
+    }
 }