[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Core component classes.
   4   *
   5   * @package BuddyPress
   6   * @subpackage Core
   7   */
   8  
   9  // Exit if accessed directly
  10  defined( 'ABSPATH' ) || exit;
  11  
  12  /**
  13   * Represents a recipient that an email will be sent to.
  14   *
  15   * @since 2.5.0
  16   */
  17  class BP_Email_Recipient extends BP_Email_Participant {
  18  
  19      /**
  20       * Optional. A `WP_User` object relating to this recipient.
  21       *
  22       * @since 2.5.0
  23       *
  24       * @var WP_User
  25       */
  26      protected $user_object = null;
  27  
  28      /**
  29       * Constructor.
  30       *
  31       * @since 2.5.0
  32       *
  33       * @param string|array|int|WP_User $email_or_user Either a email address, user ID, WP_User object,
  34       *                                                or an array containing any combination of the above.
  35       * @param string $name Optional. If $email_or_user is a string, this is the recipient's name.
  36       */
  37  	public function __construct( $email_or_user, $name = '' ) {
  38          $name = sanitize_text_field( $name );
  39  
  40          // User ID, email address or WP_User object.
  41          if ( is_int( $email_or_user ) || ( is_string( $email_or_user ) && is_email( $email_or_user ) ) || is_object( $email_or_user ) ) {
  42              // We already have a WP user.
  43              if ( is_object( $email_or_user ) ) {
  44                  $this->user_object = $email_or_user;
  45  
  46              // Query for WP user by user ID.
  47              } elseif ( is_int( $email_or_user ) ) {
  48                  $this->user_object = get_user_by( 'id', $email_or_user );
  49              }
  50  
  51              // Set email address.
  52              if ( empty( $this->user_object ) && is_email( $email_or_user ) ) {
  53                  $address = $email_or_user;
  54              }
  55  
  56          // Array or miscellaneous string.
  57          } else {
  58              if ( ! is_array( $email_or_user ) ) {
  59                  $email_or_user = array( $email_or_user => $name );
  60              }
  61  
  62              // Handle numeric arrays.
  63              if ( is_int( key( $email_or_user ) ) ) {
  64                  $address = current( $email_or_user );
  65              } else {
  66                  $address = key( $email_or_user );
  67                  $name    = current( $email_or_user );
  68              }
  69          }
  70  
  71          // Set address if we have one.
  72          if ( ! empty( $address ) ) {
  73              $this->set_address( sanitize_email( $address ) );
  74          }
  75  
  76          // Still no user object; try to query user by email address.
  77          if ( empty( $this->user_object ) ) {
  78              $this->get_user( 'search-email' );
  79          }
  80  
  81          // We have a user object; so set address and name from DB.
  82          if ( $this->user_object ) {
  83              // This is escaped with esc_html in bp_core_get_user_displayname()
  84              $wp_name = wp_specialchars_decode( bp_core_get_user_displayname( $this->user_object->ID ), ENT_QUOTES );
  85  
  86              $this->set_address( $this->user_object->user_email );
  87              $this->set_name( $wp_name );
  88  
  89          }
  90  
  91          // Custom name override.
  92          if ( $name ) {
  93              $this->set_name( $name );
  94          }
  95  
  96          /**
  97           * Fires inside __construct() method for BP_Email_Recipient class.
  98           *
  99           * @since 2.5.0
 100           *
 101           * @param string|array|int|WP_User $email_or_user Either a email address, user ID, WP_User object,
 102           *                                                or an array containing any combination of the above.
 103           * @param string $name If $email_or_user is a string, this is the recipient's name.
 104           * @param BP_Email_Recipient $this Current instance of the email type class.
 105           */
 106          do_action( 'bp_email_recipient', $email_or_user, $name, $this );
 107      }
 108  
 109      /**
 110       * Get recipient's address.
 111       *
 112       * @since 2.5.0
 113       *
 114       * @return string
 115       */
 116  	public function get_address() {
 117          $address = parent::get_address();
 118  
 119          /**
 120           * Filters the recipient's address before it's returned.
 121           *
 122           * @since 2.5.0
 123           *
 124           * @param string             $address   Recipient's address.
 125           * @param BP_Email_Recipient $recipient Current instance of the email recipient class.
 126           */
 127          return apply_filters( 'bp_email_recipient_get_address', $address, $this );
 128      }
 129  
 130      /**
 131       * Get recipient's name.
 132       *
 133       * @since 2.5.0
 134       *
 135       * @return string
 136       */
 137  	public function get_name() {
 138          $name = parent::get_name();
 139  
 140          /**
 141           * Filters the recipient's name before it's returned.
 142           *
 143           * @since 2.5.0
 144           *
 145           * @param string             $name      Recipient's name.
 146           * @param BP_Email_Recipient $recipient Current instance of the email recipient class.
 147           */
 148          return apply_filters( 'bp_email_recipient_get_name', $name, $this );
 149      }
 150  
 151      /**
 152       * Get WP_User object for this recipient.
 153       *
 154       * @since 2.5.0
 155       *
 156       * @param string $transform Optional. How to transform the return value.
 157       *                          Accepts 'raw' (default) or 'search-email'.
 158       * @return WP_User|null WP_User object, or null if not set.
 159       */
 160  	public function get_user( $transform = 'raw' ) {
 161  
 162          // If transform "search-email", find the WP_User if not already set.
 163          if ( $transform === 'search-email' && ! $this->user_object && $this->address ) {
 164              $this->user_object = get_user_by( 'email', $this->address );
 165          }
 166  
 167          /**
 168           * Filters the WP_User object for this recipient before it's returned.
 169           *
 170           * @since 2.5.0
 171           *
 172           * @param WP_User $name WP_User object for this recipient, or null if not set.
 173           * @param string $transform Optional. How the return value was transformed.
 174           *                          Accepts 'raw' (default) or 'search-email'.
 175           * @param BP_Email $recipient $this Current instance of the email recipient class.
 176           */
 177          return apply_filters( 'bp_email_recipient_get_user', $this->user_object, $transform, $this );
 178      }
 179  }