/bp-core/classes/class-bp-email-recipient.php

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