From 99cfb00d1398ea040aca7ddd658560360b8b5b70 Mon Sep 17 00:00:00 2001
From: John Blackbourn <johnbillion@git.wordpress.org>
Date: Sun, 20 Dec 2020 15:07:23 +0000
Subject: [PATCH] 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


git-svn-id: https://develop.svn.wordpress.org/trunk@49844 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/pluggable.php | 38 +++++++++++++++++++++++++++++------
 tests/phpunit/tests/mail.php  | 16 +++++++++++++++
 2 files changed, 48 insertions(+), 6 deletions(-)

diff --git a/src/wp-includes/pluggable.php b/src/wp-includes/pluggable.php
index 0f984a7e58..7dee482170 100644
--- a/src/wp-includes/pluggable.php
+++ b/src/wp-includes/pluggable.php
@@ -161,12 +161,12 @@ if ( ! function_exists( 'wp_mail' ) ) :
 	 *
 	 * @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() ) {
 		// Compact the input, apply the filters, and extract them back out.
@@ -188,6 +188,32 @@ if ( ! function_exists( 'wp_mail' ) ) :
 		 */
 		$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'] ) ) {
 			$to = $atts['to'];
 		}
diff --git a/tests/phpunit/tests/mail.php b/tests/phpunit/tests/mail.php
index 25d6fa3058..fabeb092dc 100644
--- a/tests/phpunit/tests/mail.php
+++ b/tests/phpunit/tests/mail.php
@@ -415,4 +415,20 @@ class Tests_Mail extends WP_UnitTestCase {
 		$phpmailer = $GLOBALS['phpmailer'];
 		$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 );
+	}
 }