Ticket #6592: 6592-core.01.patch

src/bp-core/bp-core-classes.php

@@ -25 +25 @@
 require dirname( __FILE__ ) . '/classes/class-bp-attachment.php';
 require dirname( __FILE__ ) . '/classes/class-bp-attachment-avatar.php';
 require dirname( __FILE__ ) . '/classes/class-bp-attachment-cover-image.php';
+require dirname( __FILE__ ) . '/classes/class-bp-email-recipient.php';
+require dirname( __FILE__ ) . '/classes/class-bp-email.php';
+require dirname( __FILE__ ) . '/classes/class-bp-email-delivery.php';
+require dirname( __FILE__ ) . '/classes/class-bp-phpmailer.php';

src/bp-core/bp-core-filters.php

@@ -53 +53 @@
 add_filter( 'bp_core_render_message_content', 'shortcode_unautop' );
 add_filter( 'bp_core_render_message_content', 'wp_kses_data', 5   );
 
+// Emails.
+add_filter( 'bp_email_set_content_html', 'wp_filter_post_kses', 6 );
+add_filter( 'bp_email_set_content_html', 'stripslashes', 8 );
+add_filter( 'bp_email_set_content_plaintext', 'wp_strip_all_tags', 6 );
+add_filter( 'bp_email_set_subject', 'sanitize_text_field', 6 );
+
+
 /**
  * Template Compatibility.
  *
@@ -1038 +1045 @@
         return $params;
 }
 add_filter( 'dynamic_sidebar_params', '_bp_core_inject_bp_widget_css_class' );
+
+/**
+ * Add custom headers to outgoing emails.
+ *
+ * @since 2.5.0
+ *
+ * @param array $headers
+ * @param string $property Name of property. Unused.
+ * @param string $transform Return value transformation. Unused.
+ * @param BP_Email $email Email object reference.
+ * @return array
+ */
+function bp_email_set_default_headers( $headers, $property, $transform, $email ) {
+        $headers['X-BuddyPress']      = bp_get_version();
+        $headers['X-BuddyPress-Type'] = $email->get( 'type' );
+
+        return $headers;
+}
+add_filter( 'bp_email_get_headers', 'bp_email_set_default_headers', 6, 4 );
+
+/**
+ * Add default email tokens.
+ *
+ * @since 2.5.0
+ *
+ * @param array $tokens Email tokens.
+ * @param string $property_name Unused.
+ * @param string $transform Unused.
+ * @param BP_Email $email Email being sent.
+ * @return array
+ */
+function bp_email_set_default_tokens( $tokens, $property_name, $transform, $email ) {
+        $tokens['site.admin-email'] = bp_get_option( 'admin_email' );
+        $tokens['site.url']         = home_url();
+
+        // These options are escaped with esc_html on the way into the database in sanitize_option().
+        $tokens['site.description'] = wp_specialchars_decode( bp_get_option( 'blogdescription' ), ENT_QUOTES );
+        $tokens['site.name']        = wp_specialchars_decode( bp_get_option( 'blogname' ), ENT_QUOTES );
+
+        // Default values for tokens set conditionally below.
+        $tokens['unsubscribe'] = '';
+
+
+        // Who is the email going to?
+        $recipient = $email->get( 'to' );
+        if ( $recipient ) {
+
+                $user = array_shift( $recipient )->get_user( 'search-email' );
+                if ( $user ) {
+
+                        // Unsubscribe link.
+                        $tokens['unsubscribe'] = esc_url( sprintf(
+                                '%s%s/notifications/',
+                                bp_core_get_user_domain( $user->ID ),
+                                function_exists( 'bp_get_settings_slug' ) ? bp_get_settings_slug() : 'settings'
+                        ) );
+                }
+        }
+
+        return $tokens;
+}
+add_filter( 'bp_email_get_tokens', 'bp_email_set_default_tokens', 6, 4 );

new file src/bp-core/classes/class-bp-email-delivery.php

@@ +1 @@
+<?php
+/**
+ * Core component classes.
+ *
+ * @package BuddyPress
+ * @subpackage Core
+ */
+
+// Exit if accessed directly
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Email delivery implementation base class.
+ *
+ * When implementing support for an email delivery service into BuddyPress,
+ * you are required to create a class that implements this interface.
+ *
+ * @since 2.5.0
+ */
+interface BP_Email_Delivery {
+
+        /**
+         * Send email(s).
+         *
+         * @since 2.5.0
+         *
+         * @param BP_Email $email Email to send.
+         * @return bool|WP_Error Returns true if email send, else a descriptive WP_Error.
+         */
+        public function bp_email( BP_Email $email );
+}

new file src/bp-core/classes/class-bp-email-recipient.php

@@ +1 @@
+<?php
+/**
+ * Core component classes.
+ *
+ * @package BuddyPress
+ * @subpackage Core
+ */
+
+// Exit if accessed directly
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Represents a recipient that an email will be sent to.
+ *
+ * @since 2.5.0
+ */
+class BP_Email_Recipient {
+
+        /**
+         * Recipient's email address.
+         *
+         * @since 2.5.0
+         *
+         * @var string
+         */
+        protected $address = '';
+
+        /**
+         * Recipient's name.
+         *
+         * @since 2.5.0
+         *
+         * @var string
+         */
+        protected $name = '';
+
+        /**
+         * Optional. A `WP_User` object relating to this recipient.
+         *
+         * @since 2.5.0
+         *
+         * @var WP_User
+         */
+        protected $user_object = null;
+
+        /**
+         * Constructor.
+         *
+         * @since 2.5.0
+         *
+         * @param string|array|int|WP_User $email_or_user Either a email address, user ID, WP_User object,
+         *                                                or an array containg the address and name.
+         * @param string $name Optional. If $email_or_user is a string, this is the recipient's name.
+         */
+        public function __construct( $email_or_user, $name = '' ) {
+                $name = sanitize_text_field( $name );
+
+                // User ID, WP_User object.
+                if ( is_int( $email_or_user ) || is_object( $email_or_user ) ) {
+                        $this->user_object = is_object( $email_or_user ) ? $email_or_user : get_user_by( 'ID', $email_or_user );
+
+                        if ( $this->user_object ) {
+                                // This is escaped with esc_html in bp_core_get_user_displayname()
+                                $name = wp_specialchars_decode( bp_core_get_user_displayname( $this->user_object->ID ), ENT_QUOTES );
+
+                                $this->address = $this->user_object->user_email;
+                                $this->name    = sanitize_text_field( $name );
+                        }
+
+                // Array, address, and name.
+                } else {
+                        if ( ! is_array( $email_or_user ) ) {
+                                $email_or_user = array( $email_or_user => $name );
+                        }
+
+                        // Handle numeric arrays.
+                        if ( is_int( key( $email_or_user ) ) ) {
+                                $address = current( $email_or_user );
+                        } else {
+                                $address = key( $email_or_user );
+                                $name    = current( $email_or_user );
+                        }
+
+                        if ( is_email( $address ) ) {
+                                $this->address = sanitize_email( $address );
+                        }
+
+                        $this->name = $name;
+                }
+
+                /**
+                 * Fires inside __construct() method for BP_Email_Recipient class.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param string|array|int|WP_User $email_or_user Either a email address, user ID, WP_User object,
+                 *                                                or an array containg the address and name.
+                 * @param string $name If $email_or_user is a string, this is the recipient's name.
+                 * @param BP_Email_Recipient $this Current instance of the email type class.
+                 */
+                do_action( 'bp_email_recipient', $email_or_user, $name, $this );
+        }
+
+        /**
+         * Get recipient's address.
+         *
+         * @since 2.5.0
+         *
+         * @return string
+         */
+        public function get_address() {
+
+                /**
+                 * Filters the recipient's address before it's returned.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param string $address Recipient's address.
+                 * @param BP_Email $recipient $this Current instance of the email recipient class.
+                 */
+                return apply_filters( 'bp_email_recipient_get_address', $this->address, $this );
+        }
+
+        /**
+         * Get recipient's name.
+         *
+         * @since 2.5.0
+         *
+         * @return string
+         */
+        public function get_name() {
+
+                /**
+                 * Filters the recipient's name before it's returned.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param string $name Recipient's name.
+                 * @param BP_Email $recipient $this Current instance of the email recipient class.
+                 */
+                return apply_filters( 'bp_email_recipient_get_name', $this->name, $this );
+        }
+
+        /**
+         * Get WP_User object for this recipient.
+         *
+         * @since 2.5.0
+         *
+         * @param string $transform Optional. How to transform the return value.
+         *                          Accepts 'raw' (default) or 'search-email'.
+         * @return WP_User|null WP_User object, or null if not set.
+         */
+        public function get_user( $transform = 'raw' ) {
+
+                // If transform "search-email", find the WP_User if not already set.
+                if ( $transform === 'search-email' && ! $this->user_object && $this->address ) {
+                        $this->user_object = get_user_by( 'email', $this->address );
+                }
+
+                /**
+                 * Filters the WP_User object for this recipient before it's returned.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param WP_User $name WP_User object for this recipient, or null if not set.
+                 * @param string $transform Optional. How the return value was transformed.
+                 *                          Accepts 'raw' (default) or 'search-email'.
+                 * @param BP_Email $recipient $this Current instance of the email recipient class.
+                 */
+                return apply_filters( 'bp_email_recipient_get_name', $this->user_object, $transform, $this );
+        }
+}

new file src/bp-core/classes/class-bp-email.php

@@ +1 @@
+<?php
+/**
+ * Core component classes.
+ *
+ * @package BuddyPress
+ * @subpackage Core
+ */
+
+// Exit if accessed directly
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Represents an email that will be sent to member(s).
+ *
+ * @since 2.5.0
+ */
+class BP_Email {
+        /**
+         * Addressee details (BCC).
+         *
+         * @since 2.5.0
+         *
+         * @var BP_Email_Recipient[] BCC recipients.
+         */
+        protected $bcc = array();
+
+        /**
+         * Addressee details (CC).
+         *
+         * @since 2.5.0
+         *
+         * @var BP_Email_Recipient[] CC recipients.
+         */
+        protected $cc = array();
+
+        /**
+         * Email content (HTML).
+         *
+         * @since 2.5.0
+         *
+         * @var string
+         */
+        protected $content_html = '';
+
+        /**
+         * Email content (plain text).
+         *
+         * @since 2.5.0
+         *
+         * @var string
+         */
+        protected $content_plaintext = '';
+
+        /**
+         * The content type to send the email in ("html" or "plaintext").
+         *
+         * @since 2.5.0
+         *
+         * @var string
+         */
+        protected $content_type = 'html';
+
+        /**
+         * Sender details.
+         *
+         * @since 2.5.0
+         *
+         * @var BP_Email_Recipient Sender details.
+         */
+        protected $from = null;
+
+        /**
+         * Email headers.
+         *
+         * @since 2.5.0
+         *
+         * @var string[] Associative pairing of email header name/value.
+         */
+        protected $headers = array();
+
+        /**
+         * The Post object (the source of the email's content and subject).
+         *
+         * @since 2.5.0
+         *
+         * @var WP_Post
+         */
+        protected $post_object = null;
+
+        /**
+         * Reply To details.
+         *
+         * @since 2.5.0
+         *
+         * @var BP_Email_Recipient "Reply to" details.
+         */
+        protected $reply_to = null;
+
+        /**
+         * Email subject.
+         *
+         * @since 2.5.0
+         *
+         * @var string
+         */
+        protected $subject = '';
+
+        /**
+         * Email template (the HTML wrapper around the email content).
+         *
+         * @since 2.5.0
+         *
+         * @var string
+         */
+        protected $template = '{{{content}}}';
+
+        /**
+         * Addressee details (to).
+         *
+         * @since 2.5.0
+         *
+         * @var BP_Email_Recipient[] Email recipients.
+         * }
+         */
+        protected $to = array();
+
+        /**
+         * Unique identifier for this particular type of email.
+         *
+         * @since 2.5.0
+         *
+         * @var string
+         */
+        protected $type = '';
+
+        /**
+         * Token names and replacement values for this email.
+         *
+         * @since 2.5.0
+         *
+         * @var string[] Associative pairing of token name (key) and replacement value (value).
+         */
+        protected $tokens = array();
+
+        /**
+         * Constructor.
+         *
+         * Set the email type and default "from" and "reply to" name and address.
+         *
+         * @since 2.5.0
+         *
+         * @param string $email_type Unique identifier for a particular type of email.
+         */
+        public function __construct( $email_type ) {
+                $this->type = $email_type;
+
+                // SERVER_NAME isn't always set (e.g CLI).
+                if ( ! empty( $_SERVER['SERVER_NAME'] ) ) {
+                        $domain = strtolower( $_SERVER['SERVER_NAME'] );
+                        if ( substr( $domain, 0, 4 ) === 'www.' ) {
+                                $domain = substr( $domain, 4 );
+                        }
+
+                } elseif ( function_exists( 'gethostname' ) && gethostname() !== false ) {
+                        $domain = gethostname();
+
+                } elseif ( php_uname( 'n' ) !== false ) {
+                        $domain = php_uname( 'n' );
+
+                } else {
+                        $domain = 'localhost.localdomain';
+                }
+
+                // This was escaped with esc_html on the way into the database in sanitize_option().
+                $site_name = wp_specialchars_decode( bp_get_option( 'blogname' ), ENT_QUOTES );
+
+                $this->from( "wordpress@$domain", $site_name );
+                $this->reply_to( bp_get_option( 'admin_email' ), $site_name );
+
+                /**
+                 * Fires inside __construct() method for BP_Email class.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param string $email_type Unique identifier for this type of email.
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                do_action( 'bp_email', $email_type, $this );
+        }
+
+
+        /*
+         * Psuedo setters/getters.
+         */
+
+        /**
+         * Getter function to expose object properties.
+         *
+         * Unlike most other methods in this class, this one is not chainable.
+         *
+         * @since 2.5.0
+         *
+         * @param string $property_name Property to access.
+         * @param string $transform Optional. How to transform the return value.
+         *                          Accepts 'raw' (default) or 'replace-tokens'.
+         * @return mixed Returns null if property does not exist, otherwise the value.
+         */
+        public function get( $property_name, $transform = 'raw' ) {
+                // "content" is replaced by HTML or plain text depending on $content_type.
+                if ( $property_name === 'content' ) {
+                        $property_name = 'content_' . $this->get( 'content_type' );
+
+                        if ( ! in_array( $property_name, array( 'content_html', 'content_plaintext', ), true ) ) {
+                                $property_name = 'content_html';
+                        }
+                }
+
+                if ( ! property_exists( $this, $property_name ) ) {
+                        return null;
+                }
+
+
+                /**
+                 * Filters the value of the specified email property.
+                 *
+                 * This is a dynamic filter dependent on the specified key.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param mixed $property_value Property value.
+                 * @param string $property_name
+                 * @param string $transform How to transform the return value.
+                 *                          Accepts 'raw' (default) or 'replace-tokens'.
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                $retval = apply_filters( "bp_email_get_{$property_name}", $this->$property_name, $property_name, $transform, $this );
+
+                switch ( $transform ) {
+                        // Special-case to fill the $template with the email $content.
+                        case 'add-content':
+                                $retval = str_replace( '{{{content}}}', nl2br( $this->get( 'content', 'replace-tokens' ) ), $retval );
+                                // Fall through.
+
+                        case 'replace-tokens':
+                                $retval = self::replace_tokens( $retval, $this->get( 'tokens', 'raw' ) );
+                                // Fall through.
+
+                        case 'raw':
+                        default:
+                                // Do nothing.
+                }
+
+                /**
+                 * Filters the value of the specified email $property.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param string $retval Property value.
+                 * @param string $property_name
+                 * @param string $transform How to transform the return value.
+                 *                          Accepts 'raw' (default) or 'replace-tokens'.
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                return apply_filters( 'bp_email_get_property', $retval, $property_name, $transform, $this );
+        }
+
+        /**
+         * Set email headers.
+         *
+         * Does NOT let you override to/from, etc. Use the methods provided to set those.
+         *
+         * @since 2.5.0
+         *
+         * @param string[] $headers Key/value pairs of header name/values (strings).
+         * @return BP_Email
+         */
+        public function headers( array $headers ) {
+                $new_headers = array();
+
+                foreach ( $headers as $name => $content ) {
+                        $content = str_replace( ':', '', $content );
+                        $name    = str_replace( ':', '', $name );
+
+                        $new_headers[ sanitize_key( $name ) ] = sanitize_text_field( $content );
+                }
+
+                /**
+                 * Filters the new value of the email's "headers" property.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param string[] $new_headers Key/value pairs of new header name/values (strings).
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                $this->headers = apply_filters( 'bp_email_set_headers', $new_headers, $this );
+
+                return $this;
+        }
+
+        /**
+         * Set the email's "bcc" address.
+         *
+         * To set a single address, the first parameter is the address and the second the name.
+         * You can also pass a user ID or a WP_User object.
+         *
+         * To set multiple addresses, for each array item, the key is the email address and
+         * the value is the name.
+         *
+         * @since 2.5.0
+         *
+         * @param string|array|int|WP_User $bcc_address Either a email address, user ID, WP_User object,
+         *                                              or an array containg the address and name.
+         * @param string $name Optional. If $bcc_address is a string, this is the recipient's name.
+         * @return BP_Email
+         */
+        public function bcc( $bcc_address, $name = '' ) {
+                $bcc = array( new BP_Email_Recipient( $bcc_address, $name ) );
+
+                /**
+                 * Filters the new value of the email's "BCC" property.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param BP_Email_Recipient[] $bcc BCC recipients.
+                 * @param string|array|int|WP_User $bcc_address Either a email address, user ID, WP_User object,
+                 *                                              or an array containg the address and name.
+                 * @param string $name Optional. If $bcc_address is a string, this is the recipient's name.
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                $this->bcc = apply_filters( 'bp_email_set_bcc', $bcc, $bcc_address, $name, $this );
+
+                return $this;
+        }
+
+        /**
+         * Set the email's "cc" address.
+         *
+         * To set a single address, the first parameter is the address and the second the name.
+         * You can also pass a user ID or a WP_User object.
+         *
+         * To set multiple addresses, for each array item, the key is the email address and
+         * the value is the name.
+         *
+         * @since 2.5.0
+         *
+         * @param string|array|int|WP_User $cc_address Either a email address, user ID, WP_User object,
+         *                                             or an array containg the address and name.
+         * @param string $name Optional. If $cc_address is a string, this is the recipient's name.
+         * @return BP_Email
+         */
+        public function cc( $cc_address, $name = '' ) {
+                $cc = array( new BP_Email_Recipient( $cc_address, $name ) );
+
+                /**
+                 * Filters the new value of the email's "CC" property.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param BP_Email_Recipient[] $cc CC recipients.
+                 * @param string|array|int|WP_User $cc_address Either a email address, user ID, WP_User object,
+                 *                                             or an array containg the address and name.
+                 * @param string $name Optional. If $cc_address is a string, this is the recipient's name.
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                $this->cc = apply_filters( 'bp_email_set_cc', $cc, $cc_address, $name, $this );
+
+                return $this;
+        }
+
+        /**
+         * Set the email content (HTML).
+         *
+         * @since 2.5.0
+         *
+         * @param string $content HTML email content.
+         * @return BP_Email
+         */
+        public function content_html( $content ) {
+
+                /**
+                 * Filters the new value of the email's "content" property (HTML).
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param string $content HTML email content.
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                $this->content_html = apply_filters( 'bp_email_set_content_html', $content, $this );
+
+                return $this;
+        }
+
+        /**
+         * Set the email content (plain text).
+         *
+         * @since 2.5.0
+         *
+         * @param string $content Plain text email content.
+         * @return BP_Email
+         */
+        public function content_plaintext( $content ) {
+
+                /**
+                 * Filters the new value of the email's "content" property (plain text).
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param string $content Plain text email content.
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                $this->content_plaintext = apply_filters( 'bp_email_set_content_plaintext', $content, $this );
+
+                return $this;
+        }
+
+        /**
+         * Set the content type (HTML or plain text) to send the email in.
+         *
+         * @since 2.5.0
+         *
+         * @param string $content_type Email content type ("html" or "plaintext").
+         * @return BP_Email
+         */
+        public function content_type( $content_type ) {
+                if ( ! in_array( $content_type, array( 'html', 'plaintext', ), true ) ) {
+                        $class        = get_class_vars( get_class() );
+                        $content_type = $class['content_type'];
+                }
+
+                /**
+                 * Filters the new value of the email's "content type" property.
+                 *
+                 * The content type (HTML or plain text) to send the email in.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param string $content_type Email content type ("html" or "plaintext").
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                $this->content_type = apply_filters( 'bp_email_set_content_type', $content_type, $this );
+
+                return $this;
+        }
+
+        /**
+         * Set the email's "from" address and name.
+         *
+         * @since 2.5.0
+         *
+         * @param string|array|int|WP_User $email_address Either a email address, user ID, WP_User object,
+         *                                                or an array containg the address and name.
+         * @param string $name Optional. If $email_address is a string, this is the recipient's name.
+         * @return BP_Email
+         */
+        public function from( $email_address, $name = '' ) {
+                $from = new BP_Email_Recipient( $email_address, $name );
+
+                /**
+                 * Filters the new value of the email's "from" property.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param BP_Email_Recipient $from Sender details.
+                 * @param string|array|int|WP_User $email_address Either a email address, user ID, WP_User object,
+                 *                                                or an array containg the address and name.
+                 * @param string $name Optional. If $email_address is a string, this is the recipient's name.
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                $this->from = apply_filters( 'bp_email_set_from', $from, $email_address, $name, $this );
+
+                return $this;
+        }
+
+        /**
+         * Set the Post object containing the email content template.
+         *
+         * Also sets the email's subject, content, and template from the Post, for convenience.
+         *
+         * @since 2.5.0
+         *
+         * @param WP_Post $post
+         * @return BP_Email
+         */
+        public function post_object( WP_Post $post ) {
+
+                /**
+                 * Filters the new value of the email's "post object" property.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param WP_Post $post A Post.
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                $this->post_object = apply_filters( 'bp_email_set_post_object', $post, $this );
+
+                if ( is_a( $this->post_object, 'WP_Post' ) ) {
+                        $this->subject( $this->post_object->post_title )
+                                ->content_html( $this->post_object->post_content )
+                                ->content_plaintext( $this->post_object->post_excerpt );
+
+                        ob_start();
+
+                        // Load the template.
+                        bp_locate_template( bp_email_get_template( $this->post_object ), true, false );
+                        $this->template( ob_get_contents() );
+
+                ob_end_clean();
+                }
+
+                return $this;
+        }
+
+        /**
+         * Set the email's "reply to" address and name.
+         *
+         * @since 2.5.0
+         *
+         * @param string|array|int|WP_User $email_address Either a email address, user ID, WP_User object,
+         *                                                or an array containg the address and name.
+         * @param string $name Optional. If $email_address is a string, this is the recipient's name.
+         * @return BP_Email
+         */
+        public function reply_to( $email_address, $name = '' ) {
+                $reply_to = new BP_Email_Recipient( $email_address, $name );
+
+                /**
+                 * Filters the new value of the email's "reply to" property.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param BP_Email_Recipient $reply_to "Reply to" recipient.
+                 * @param string|array|int|WP_User $email_address Either a email address, user ID, WP_User object,
+                 *                                                or an array containg the address and name.
+                 * @param string $name Optional. If $email_address is a string, this is the recipient's name.
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                $this->reply_to = apply_filters( 'bp_email_set_reply_to', $reply_to, $email_address, $name, $this );
+
+                return $this;
+        }
+
+        /**
+         * Set the email subject.
+         *
+         * @since 2.5.0
+         *
+         * @param string $subject Email subject.
+         * @return BP_Email
+         */
+        public function subject( $subject ) {
+
+                /**
+                 * Filters the new value of the subject email property.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param string $subject Email subject.
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                $this->subject = apply_filters( 'bp_email_set_subject', $subject, $this );
+
+                return $this;
+        }
+
+        /**
+         * Set the email template (the HTML wrapper around the email content).
+         *
+         * This needs to include the string "{{{content}}}" to have the post content added
+         * when the email template is rendered.
+         *
+         * @since 2.5.0
+         *
+         * @param string $template Email template. Assumed to be HTML.
+         * @return BP_Email
+         */
+        public function template( $template ) {
+
+                /**
+                 * Filters the new value of the template email property.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param string $template Email template. Assumed to be HTML.
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                $this->template = apply_filters( 'bp_email_set_template', $template, $this );
+
+                return $this;
+        }
+
+        /**
+         * Set the email's "to" address.
+         *
+         * IMPORTANT NOTE: the assumption with all emails sent by (and belonging to) BuddyPress itself
+         * is that there will only be a single `$to_address`. This is to simplify token and templating
+         * logic (for example, if multiple recipients, the "unsubscribe" link in the emails will all
+         * only link to the first recipient).
+         *
+         * To set a single address, the first parameter is the address and the second the name.
+         * You can also pass a user ID or a WP_User object.
+         *
+         * To set multiple addresses, for each array item, the key is the email address and
+         * the value is the name.
+         *
+         * @since 2.5.0
+         *
+         * @param string|array|int|WP_User $to_address Either a email address, user ID, WP_User object,
+         *                                             or an array containg the address and name.
+         * @param string $name Optional. If $to_address is a string, this is the recipient's name.
+         * @return BP_Email
+         */
+        public function to( $to_address, $name = '' ) {
+                $to = array( new BP_Email_Recipient( $to_address, $name ) );
+
+                /**
+                 * Filters the new value of the email's "to" property.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param BP_Email_Recipient[] "To" recipients.
+                 * @param string $to_address "To" address.
+                 * @param string $name "To" name.
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                $this->to = apply_filters( 'bp_email_set_to', $to, $to_address, $name, $this );
+
+                return $this;
+        }
+
+        /**
+         * Set token names and replacement values for this email.
+         *
+         * In templates, tokens are inserted with a Handlebars-like syntax, e.g. `{{token_name}}`.
+         * { and } are reserved characters. There's no need to specify these brackets in your token names.
+         *
+         * @since 2.5.0
+         *
+         * @param string[] $tokens Associative array, contains key/value pairs of token name/value.
+         *                         Values are a string or a callable function.
+         * @return BP_Email
+         */
+        public function tokens( array $tokens ) {
+                $formatted_tokens = array();
+
+                foreach ( $tokens as $name => $value ) {
+                        $name                      = str_replace( array( '{', '}' ), '', sanitize_text_field( $name ) );
+                        $formatted_tokens[ $name ] = $value;
+                }
+
+                /**
+                 * Filters the new value of the email's "tokens" property.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param string[] $formatted_tokens Associative pairing of token names (key) and replacement values (value).
+                 * @param string[] $tokens Associative pairing of unformatted token names (key) and replacement values (value).
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                $this->tokens = apply_filters( 'bp_email_set_tokens', $formatted_tokens, $tokens, $this );
+
+                return $this;
+        }
+
+
+        /*
+         * Sanitisation and validation logic.
+         */
+
+        /**
+         * Check that we'd be able to send this email.
+         *
+         * Unlike most other methods in this class, this one is not chainable.
+         *
+         * @since 2.5.0
+         *
+         * @return bool|WP_Error Returns true if validation succesful, else a descriptive WP_Error.
+         */
+        public function validate() {
+                $retval = true;
+
+                // BCC, CC, and token properties are optional.
+                if (
+                        ! $this->get( 'from' ) ||
+                        ! $this->get( 'to' ) ||
+                        ! $this->get( 'subject' ) ||
+                        ! $this->get( 'content' ) ||
+                        ! $this->get( 'template' )
+                ) {
+                        $retval = new WP_Error( 'missing_parameter', __CLASS__, $this );
+                }
+
+                /**
+                 * Filters whether the email passes basic validation checks.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param bool|WP_Error $retval Returns true if validation succesful, else a descriptive WP_Error.
+                 * @param BP_Email $this Current instance of the email type class.
+                 */
+                return apply_filters( 'bp_email_validate', $retval, $this );
+        }
+
+
+        /*
+         * Utility functions.
+         *
+         * Unlike other methods in this class, utility functions are not chainable.
+         */
+
+        /**
+         * Replace all tokens in the input with appropriate values.
+         *
+         * Unlike most other methods in this class, this one is not chainable.
+         *
+         * @since 2.5.0
+         *
+         * @param string $text
+         * @param array $tokens Token names and replacement values for the $text.
+         * @return string
+         */
+        public static function replace_tokens( $text, $tokens ) {
+                $unescaped = array();
+                $escaped   = array();
+
+                foreach ( $tokens as $token => $value ) {
+                        if ( is_callable( $value ) ) {
+                                $value = call_user_func( $value );
+                        }
+
+                        // Some tokens are objects or arrays for backwards compatibilty. See bp_core_deprecated_email_filters().
+                        if ( ! is_scalar( $value ) ) {
+                                continue;
+                        }
+
+                        $unescaped[ '{{{' . $token . '}}}' ] = $value;
+                        $escaped[ '{{' . $token . '}}' ]     = esc_html( $value );
+                }
+
+                $text = strtr( $text, $unescaped );  // Do first.
+                $text = strtr( $text, $escaped );
+
+                /**
+                 * Filters text that has had tokens replaced.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param string $text
+                 * @param array $tokens Token names and replacement values for the $text.
+                 */
+                return apply_filters( 'bp_email_replace_tokens', $text, $tokens );
+        }
+}

new file src/bp-core/classes/class-bp-phpmailer.php

@@ +1 @@
+<?php
+/**
+ * Core component classes.
+ *
+ * @package BuddyPress
+ * @subpackage Core
+ */
+
+// Exit if accessed directly
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Email delivery implementation using PHPMailer.
+ *
+ * @since 2.5.0
+ */
+class BP_PHPMailer implements BP_Email_Delivery {
+
+        /**
+         * Constructor.
+         *
+         * @since 2.5.0
+         */
+        public function __construct() {
+                global $phpmailer;
+
+                // We'll try to use the PHPMailer object that might have been created by WordPress.
+                if ( ! ( $phpmailer instanceof PHPMailer ) ) {
+                        require_once ABSPATH . WPINC . '/class-phpmailer.php';
+                        require_once ABSPATH . WPINC . '/class-smtp.php';
+                        $phpmailer = new PHPMailer( true );
+                }
+        }
+
+        /**
+         * Send email(s).
+         *
+         * @since 2.5.0
+         *
+         * @param BP_Email $email Email to send.
+         * @return bool|WP_Error Returns true if email send, else a descriptive WP_Error.
+         */
+        public function bp_email( BP_Email $email ) {
+                global $phpmailer;
+
+                /*
+                 * Resets.
+                 */
+
+                $phpmailer->clearAllRecipients();
+                $phpmailer->clearAttachments();
+                $phpmailer->clearCustomHeaders();
+                $phpmailer->clearReplyTos();
+                $phpmailer->Sender = '';
+
+
+                /*
+                 * Set up.
+                 */
+
+                $phpmailer->IsMail();
+                $phpmailer->CharSet  = bp_get_option( 'blog_charset' );
+                $phpmailer->Hostname = self::get_hostname();
+
+
+                /*
+                 * Content.
+                 */
+
+                $phpmailer->Subject = $email->get( 'subject', 'replace-tokens' );
+                $content_plaintext  = PHPMailer::normalizeBreaks( $email->get( 'content_plaintext', 'replace-tokens' ) );
+
+                if ( $email->get( 'content_type' ) === 'html' ) {
+                        $phpmailer->msgHTML( $email->get( 'template', 'add-content' ), '', 'wp_strip_all_tags' );
+                        $phpmailer->AltBody = $content_plaintext;
+
+                } else {
+                        $phpmailer->IsHTML( false );
+                        $phpmailer->Body = $content_plaintext;
+                }
+
+                $recipient = $email->get( 'from' );
+                try {
+                        $phpmailer->SetFrom( $recipient->get_address(), $recipient->get_name() );
+                } catch ( phpmailerException $e ) {
+                }
+
+                $recipient = $email->get( 'reply_to' );
+                try {
+                        $phpmailer->addReplyTo( $recipient->get_address(), $recipient->get_name() );
+                } catch ( phpmailerException $e ) {
+                }
+
+                $recipients = $email->get( 'to' );
+                foreach ( $recipients as $recipient ) {
+                        try {
+                                $phpmailer->AddAddress( $recipient->get_address(), $recipient->get_name() );
+                        } catch ( phpmailerException $e ) {
+                        }
+                }
+
+                $recipients = $email->get( 'cc' );
+                foreach ( $recipients as $recipient ) {
+                        try {
+                                $phpmailer->AddCc( $recipient->get_address(), $recipient->get_name() );
+                        } catch ( phpmailerException $e ) {
+                        }
+                }
+
+                $recipients = $email->get( 'bcc' );
+                foreach ( $recipients as $recipient ) {
+                        try {
+                                $phpmailer->AddBcc( $recipient->get_address(), $recipient->get_name() );
+                        } catch ( phpmailerException $e ) {
+                        }
+                }
+
+                $headers = $email->get( 'headers' );
+                foreach ( $headers as $name => $content ) {
+                        $phpmailer->AddCustomHeader( $name, $content );
+                }
+
+
+                /**
+                 * Fires after PHPMailer is initialised.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @param PHPMailer $phpmailer The PHPMailer instance.
+                 */
+                do_action( 'bp_phpmailer_init', $phpmailer );
+
+                try {
+                        return $phpmailer->Send();
+                } catch ( phpmailerException $e ) {
+                        return new WP_Error( $e->getCode(), $e->getMessage(), $email );
+                }
+        }
+
+
+        /*
+         * Utility/helper functions.
+         */
+
+        /**
+         * Get an appropriate hostname for the email. Varies depending on site configuration.
+         *
+         * @since 2.5.0
+         *
+         * @return string
+         */
+        static public function get_hostname() {
+                if ( is_multisite() ) {
+                        return get_current_site()->domain;  // From fix_phpmailer_messageid()
+                }
+
+                return preg_replace( '#^https?://#i', '', bp_get_option( 'home' ) );
+        }
+}

tests/phpunit/includes/install.php

@@ -13 +13 @@
 
 require_once $config_file_path;
 require_once $tests_dir_path . '/includes/functions.php';
+require_once $tests_dir_path . '/includes/mock-mailer.php';
 
 function _load_buddypress() {
         require dirname( dirname( dirname( dirname( __FILE__ ) ) ) ) . '/src/bp-loader.php';
@@ -48 +49 @@
         $wpdb->query( "DROP TABLE {$bp_table}" );
 }
 
+function _bp_mock_mailer( $class ) {
+        return 'BP_UnitTest_Mailer';
+}
+tests_add_filter( 'bp_send_email_delivery_class', '_bp_mock_mailer' );
+
 // Install BuddyPress
 bp_version_updater();

tests/phpunit/includes/loader.php

@@ -7 +7 @@
 
 // Bootstrap BP
 require dirname( __FILE__ ) . '/../../../src/bp-loader.php';
+
+require_once( dirname( __FILE__ ) . '/mock-mailer.php' );
+function _bp_mock_mailer( $class ) {
+        return 'BP_UnitTest_Mailer';
+}
+tests_add_filter( 'bp_send_email_delivery_class', '_bp_mock_mailer' );

new file tests/phpunit/includes/mock-mailer.php

@@ +1 @@
+<?php
+
+/**
+ * Mock email delivery implementation.
+ *
+ * @since 2.5.0
+ */
+class BP_UnitTest_Mailer implements BP_Email_Delivery {
+
+        /**
+         * Send email(s).
+         *
+         * @param BP_Email $email Email to send.
+         * @return bool False if some error occurred.
+         * @since 2.5.0
+         */
+        public function bp_email( BP_Email $email ) {
+                return true;
+        }
+}

new file tests/phpunit/testcases/core/class-bp-email-recipient.php

@@ +1 @@
+<?php
+/**
+ * @group core
+ * @group BP_Email_Recipient
+ */
+class BP_Email_Recipient_Tests extends BP_UnitTestCase {
+        protected $u1;
+
+        public function setUp() {
+                parent::setUp();
+
+                $this->u1 = $this->factory->user->create( array(
+                        'display_name' => 'Unit Test',
+                        'user_email'   => 'test@example.com',
+                ) );
+        }
+
+        public function test_return_with_address_and_name() {
+                $email     = 'test@example.com';
+                $name      = 'Unit Test';
+                $recipient = new BP_Email_Recipient( $email, $name );
+
+                $this->assertSame( $email, $recipient->get_address() );
+                $this->assertSame( $name, $recipient->get_name() );
+        }
+
+        public function test_return_with_array() {
+                $email     = 'test@example.com';
+                $name      = 'Unit Test';
+                $recipient = new BP_Email_Recipient( array( $email => $name ) );
+
+                $this->assertSame( $email, $recipient->get_address() );
+                $this->assertSame( $name, $recipient->get_name() );
+        }
+
+        public function test_return_with_user_id() {
+                $recipient = new BP_Email_Recipient( $this->u1 );
+
+                $this->assertSame( 'test@example.com', $recipient->get_address() );
+                $this->assertSame( 'Unit Test', $recipient->get_name() );
+        }
+
+        public function test_return_with_wp_user_object() {
+                $recipient = new BP_Email_Recipient( get_user_by( 'id', $this->u1 ) );
+
+                $this->assertSame( 'test@example.com', $recipient->get_address() );
+                $this->assertSame( 'Unit Test', $recipient->get_name() );
+        }
+
+        public function test_return_with_address_and_optional_name() {
+                $email     = 'test@example.com';
+                $recipient = new BP_Email_Recipient( $email );
+
+                $this->assertSame( $email, $recipient->get_address() );
+                $this->assertEmpty( $recipient->get_name() );
+        }
+
+        public function test_return_with_array_and_optional_name() {
+                $email     = 'test@example.com';
+                $recipient = new BP_Email_Recipient( array( $email ) );
+
+                $this->assertSame( $email, $recipient->get_address() );
+                $this->assertEmpty( $recipient->get_name() );
+        }
+
+        public function test_should_return_empty_string_if_user_id_id_invalid() {
+                $recipient = new BP_Email_Recipient( time() );
+
+                $this->assertEmpty( $recipient->get_address() );
+                $this->assertEmpty( $recipient->get_name() );
+        }
+
+        public function test_get_wp_user_object_from_email_address() {
+                $recipient = new BP_Email_Recipient( 'test@example.com' );
+                $recipient = $recipient->get_user( 'search-email' );
+
+                $this->assertSame( $this->u1, $recipient->ID );
+                $this->assertSame( 'test@example.com', $recipient->user_email );
+        }
+}

new file tests/phpunit/testcases/core/class-bp-email.php

@@ +1 @@
+<?php
+/**
+ * @group core
+ * @group BP_Email
+ */
+class BP_Tests_Email extends BP_UnitTestCase {
+        public function setUp() {
+                parent::setUp();
+                remove_filter( 'bp_email_get_headers', 'bp_email_set_default_headers', 6, 4 );
+                remove_filter( 'bp_email_get_tokens', 'bp_email_set_default_tokens', 6, 4 );
+        }
+
+        public function tearDown() {
+                add_filter( 'bp_email_get_tokens', 'bp_email_set_default_tokens', 6, 4 );
+                add_filter( 'bp_email_get_headers', 'bp_email_set_default_headers', 6, 4 );
+                parent::tearDown();
+        }
+
+        public function test_valid_subject() {
+                $message = 'test';
+                $email   = new BP_Email( 'fake_type' );
+
+                $email->subject( $message );
+                $this->assertSame( $message, $email->get( 'subject' ) );
+        }
+
+        public function test_valid_html_content() {
+                $message = '<b>test</b>';
+                $email   = new BP_Email( 'fake_type' );
+
+                $email->content_html( $message );
+                $email->content_type( 'html' );
+
+                $this->assertSame( $message, $email->get( 'content' ) );
+        }
+
+        public function test_valid_plaintext_content() {
+                $message = 'test';
+                $email   = new BP_Email( 'fake_type' );
+
+                $email->content_plaintext( $message );
+                $email->content_type( 'plaintext' );
+
+                $this->assertSame( $message, $email->get( 'content' ) );
+        }
+
+        public function test_valid_template() {
+                $message = 'test';
+                $email   = new BP_Email( 'fake_type' );
+
+                $email->template( $message );
+                $this->assertSame( $message, $email->get( 'template' ) );
+        }
+
+        public function test_tokens() {
+                $original = array( 'test1' => 'hello', 'test2' => 'world' );
+
+                $email = new BP_Email( 'fake_type' );
+                $email->tokens( $original );
+
+                $this->assertSame(
+                        array( 'test1', 'test2' ),
+                        array_keys( $email->get( 'tokens' ) )
+                );
+
+                $this->assertSame(
+                        array( 'hello', 'world' ),
+                        array_values( $email->get( 'tokens' ) )
+                );
+        }
+
+        public function test_headers() {
+                $email = new BP_Email( 'fake_type' );
+
+                $headers = array( 'custom_header' => 'custom_value' );
+                $email->headers( $headers );
+                $this->assertSame( $headers, $email->get( 'headers' ) );
+        }
+
+        public function test_validation() {
+                $email = new BP_Email( 'fake_type' );
+                $email->from( 'test1@example.com' )->to( 'test2@example.com' )->subject( 'testing' );
+                $email->content_html( 'testing' );
+
+                $this->assertTrue( $email->validate() );
+        }
+
+        public function test_invalid_characters_are_stripped_from_tokens() {
+                $email = new BP_Email( 'fake_type' );
+                $email->tokens( array( 'te{st}1' => 'hello world' ) );
+
+                $this->assertSame(
+                        array( 'test1' ),
+                        array_keys( $email->get( 'tokens' ) )
+                );
+        }
+
+        public function test_token_are_escaped() {
+                $token = '<blink>';
+                $email = new BP_Email( 'fake_type' );
+                $email->content_html( '{{test}}' )->tokens( array( 'test' => $token ) );
+
+                $this->assertSame(
+                        esc_html( $token ),
+                        $email->get( 'content', 'replace-tokens' )
+                );
+        }
+
+        public function test_token_are_not_escaped() {
+                $token = '<blink>';
+                $email = new BP_Email( 'fake_type' );
+                $email->content_html( '{{{test}}}' )->tokens( array( 'test' => $token ) );
+
+                $this->assertSame(
+                        $token,
+                        $email->get( 'content', 'replace-tokens' )
+                );
+        }
+
+        public function test_invalid_headers() {
+                $email = new BP_Email( 'fake_type' );
+
+                $headers = array( 'custom:header' => 'custom:value' );
+                $email->headers( $headers );
+                $this->assertNotSame( $headers, $email->get( 'headers' ) );
+                $this->assertSame( array( 'customheader' => 'customvalue' ), $email->get( 'headers' ) );
+        }
+
+        public function test_validation_with_missing_required_data() {
+                $email  = new BP_Email( 'fake_type' );
+                $email->from( 'test1@example.com' )->to( 'test2@example.com' )->subject( 'testing' );  // Content
+                $result = $email->validate();
+
+                $this->assertTrue( is_wp_error( $result ) );
+                $this->assertSame( 'missing_parameter', $result->get_error_code() );
+        }
+
+        public function test_validation_with_missing_template() {
+                $email  = new BP_Email( 'fake_type' );
+                $email->from( 'test1@example.com' )->to( 'test2@example.com' )->subject( 'testing' );
+                $email->content_html( 'testing' )->template( '' );
+                $result = $email->validate();
+
+                // Template has a default value, but it can't be blank.
+                $this->assertTrue( is_wp_error( $result ) );
+                $this->assertSame( 'missing_parameter', $result->get_error_code() );
+        }
+
+        public function test_invalid_tags_should_be_removed_from_html_content() {
+                $message = '<b>hello world</b><iframe src="https://example.com"></iframe><b>hello world</b>';
+                $email   = new BP_Email( 'fake_type' );
+
+                $email->content_html( $message );
+                $email->content_type( 'html' );
+
+                $this->assertSame( '<b>hello world</b><b>hello world</b>', $email->get( 'content' ) );
+        }
+}