BP_Email

Represents an email that will be sent to member(s).

Defined (1)

The class is defined in the following location(s).

/bp-core/classes/class-bp-email.php  
  1. class BP_Email { 
  2. /** 
  3. * Addressee details (BCC). 
  4. * @since 2.5.0 
  5. * @var BP_Email_Recipient[] BCC recipients. 
  6. */ 
  7. protected $bcc = array(); 
  8.  
  9. /** 
  10. * Addressee details (CC). 
  11. * @since 2.5.0 
  12. * @var BP_Email_Recipient[] CC recipients. 
  13. */ 
  14. protected $cc = array(); 
  15.  
  16. /** 
  17. * Email content (HTML). 
  18. * @since 2.5.0 
  19. * @var string 
  20. */ 
  21. protected $content_html = ''; 
  22.  
  23. /** 
  24. * Email content (plain text). 
  25. * @since 2.5.0 
  26. * @var string 
  27. */ 
  28. protected $content_plaintext = ''; 
  29.  
  30. /** 
  31. * The content type to send the email in ("html" or "plaintext"). 
  32. * @since 2.5.0 
  33. * @var string 
  34. */ 
  35. protected $content_type = 'html'; 
  36.  
  37. /** 
  38. * Sender details. 
  39. * @since 2.5.0 
  40. * @var BP_Email_Recipient Sender details. 
  41. */ 
  42. protected $from = null; 
  43.  
  44. /** 
  45. * Email headers. 
  46. * @since 2.5.0 
  47. * @var string[] Associative pairing of email header name/value. 
  48. */ 
  49. protected $headers = array(); 
  50.  
  51. /** 
  52. * The Post object (the source of the email's content and subject). 
  53. * @since 2.5.0 
  54. * @var WP_Post 
  55. */ 
  56. protected $post_object = null; 
  57.  
  58. /** 
  59. * Reply To details. 
  60. * @since 2.5.0 
  61. * @var BP_Email_Recipient "Reply to" details. 
  62. */ 
  63. protected $reply_to = null; 
  64.  
  65. /** 
  66. * Email subject. 
  67. * @since 2.5.0 
  68. * @var string 
  69. */ 
  70. protected $subject = ''; 
  71.  
  72. /** 
  73. * Email template (the HTML wrapper around the email content). 
  74. * @since 2.5.0 
  75. * @var string 
  76. */ 
  77. protected $template = '{{{content}}}'; 
  78.  
  79. /** 
  80. * Addressee details (to). 
  81. * @since 2.5.0 
  82. * @var BP_Email_Recipient[] Email recipients. 
  83. * } 
  84. */ 
  85. protected $to = array(); 
  86.  
  87. /** 
  88. * Unique identifier for this particular type of email. 
  89. * @since 2.5.0 
  90. * @var string 
  91. */ 
  92. protected $type = ''; 
  93.  
  94. /** 
  95. * Token names and replacement values for this email. 
  96. * @since 2.5.0 
  97. * @var string[] Associative pairing of token name (key) and replacement value (value). 
  98. */ 
  99. protected $tokens = array(); 
  100.  
  101. /** 
  102. * Constructor. 
  103. * Set the email type and default "from" and "reply to" name and address. 
  104. * @since 2.5.0 
  105. * @param string $email_type Unique identifier for a particular type of email. 
  106. */ 
  107. public function __construct( $email_type ) { 
  108. $this->type = $email_type; 
  109.  
  110. // SERVER_NAME isn't always set (e.g CLI). 
  111. if ( ! empty( $_SERVER['SERVER_NAME'] ) ) { 
  112. $domain = strtolower( $_SERVER['SERVER_NAME'] ); 
  113. if ( substr( $domain, 0, 4 ) === 'www.' ) { 
  114. $domain = substr( $domain, 4 ); 
  115.  
  116. } elseif ( function_exists( 'gethostname' ) && gethostname() !== false ) { 
  117. $domain = gethostname(); 
  118.  
  119. } elseif ( php_uname( 'n' ) !== false ) { 
  120. $domain = php_uname( 'n' ); 
  121.  
  122. } else { 
  123. $domain = 'localhost.localdomain'; 
  124.  
  125. // This was escaped with esc_html on the way into the database in sanitize_option(). 
  126. $from_name = wp_specialchars_decode( bp_get_option( 'blogname' ), ENT_QUOTES ); 
  127. $from_address = "wordpress@$domain"; 
  128.  
  129. /** This filter is documented in wp-includes/pluggable.php */ 
  130. $from_address = apply_filters( 'wp_mail_from', $from_address ); 
  131.  
  132. /** This filter is documented in wp-includes/pluggable.php */ 
  133. $from_name = apply_filters( 'wp_mail_from_name', $from_name ); 
  134.  
  135. $this->set_from( $from_address, $from_name ); 
  136. $this->set_reply_to( bp_get_option( 'admin_email' ), $from_name ); 
  137.  
  138. /** 
  139. * Fires inside __construct() method for BP_Email class. 
  140. * @since 2.5.0 
  141. * @param string $email_type Unique identifier for this type of email. 
  142. * @param BP_Email $this Current instance of the email type class. 
  143. */ 
  144. do_action( 'bp_email', $email_type, $this ); 
  145.  
  146.  
  147. /** 
  148. * Setters/getters. 
  149. */ 
  150.  
  151. /** 
  152. * Getter function to expose object properties. 
  153. * Unlike most other methods in this class, this one is not chainable. 
  154. * @since 2.5.0 
  155. * @param string $property_name Property to access. 
  156. * @param string $transform Optional. How to transform the return value. 
  157. * Accepts 'raw' (default) or 'replace-tokens'. 
  158. * @return mixed Returns null if property does not exist, otherwise the value. 
  159. */ 
  160. public function get( $property_name, $transform = 'raw' ) { 
  161.  
  162. // "content" is replaced by HTML or plain text depending on $content_type. 
  163. if ( $property_name === 'content' ) { 
  164. $property_name = 'content_' . $this->get_content_type(); 
  165.  
  166. if ( ! in_array( $property_name, array( 'content_html', 'content_plaintext', ), true ) ) { 
  167. $property_name = 'content_html'; 
  168.  
  169. if ( ! property_exists( $this, $property_name ) ) { 
  170. return null; 
  171.  
  172.  
  173. /** 
  174. * Filters the value of the specified email property before transformation. 
  175. * This is a dynamic filter dependent on the specified key. 
  176. * @since 2.5.0 
  177. * @param mixed $property_value Property value. 
  178. * @param string $property_name 
  179. * @param string $transform How to transform the return value. 
  180. * Accepts 'raw' (default) or 'replace-tokens'. 
  181. * @param BP_Email $this Current instance of the email type class. 
  182. */ 
  183. $retval = apply_filters( "bp_email_get_{$property_name}", $this->$property_name, $property_name, $transform, $this ); 
  184.  
  185. switch ( $transform ) { 
  186. // Special-case to fill the $template with the email $content. 
  187. case 'add-content': 
  188. $retval = str_replace( '{{{content}}}', nl2br( $this->get_content( 'replace-tokens' ) ), $retval ); 
  189. // Fall through. 
  190.  
  191. case 'replace-tokens': 
  192. $retval = bp_core_replace_tokens_in_text( $retval, $this->get_tokens( 'raw' ) ); 
  193. // Fall through. 
  194.  
  195. case 'raw': 
  196. default: 
  197. // Do nothing. 
  198.  
  199. /** 
  200. * Filters the value of the specified email $property after transformation. 
  201. * @since 2.5.0 
  202. * @param string $retval Property value. 
  203. * @param string $property_name 
  204. * @param string $transform How to transform the return value. 
  205. * Accepts 'raw' (default) or 'replace-tokens'. 
  206. * @param BP_Email $this Current instance of the email type class. 
  207. */ 
  208. return apply_filters( 'bp_email_get_property', $retval, $property_name, $transform, $this ); 
  209.  
  210. /** 
  211. * Get email headers. 
  212. * Unlike most other methods in this class, this one is not chainable. 
  213. * @since 2.5.0 
  214. * @param string $transform Optional. How to transform the return value. 
  215. * Accepts 'raw' (default) or 'replace-tokens'. 
  216. * @return string[] Associative pairing of email header name/value. 
  217. */ 
  218. public function get_headers( $transform = 'raw' ) { 
  219. return $this->get( 'headers', $transform ); 
  220.  
  221. /** 
  222. * Get the email's "bcc" address and name. 
  223. * Unlike most other methods in this class, this one is not chainable. 
  224. * @since 2.5.0 
  225. * @param string $transform Optional. How to transform the return value. 
  226. * Accepts 'raw' (default) or 'replace-tokens'. 
  227. * @return BP_Email_Recipient[] BCC recipients. 
  228. */ 
  229. public function get_bcc( $transform = 'raw' ) { 
  230. return $this->get( 'bcc', $transform ); 
  231.  
  232. /** 
  233. * Get the email's "cc" address and name. 
  234. * Unlike most other methods in this class, this one is not chainable. 
  235. * @since 2.5.0 
  236. * @param string $transform Optional. How to transform the return value. 
  237. * Accepts 'raw' (default) or 'replace-tokens'. 
  238. * @return BP_Email_Recipient[] CC recipients. 
  239. */ 
  240. public function get_cc( $transform = 'raw' ) { 
  241. return $this->get( 'cc', $transform ); 
  242.  
  243. /** 
  244. * Get the email content. 
  245. * HTML or plaintext is returned, depending on the email's $content_type. 
  246. * Unlike most other methods in this class, this one is not chainable. 
  247. * @since 2.5.0 
  248. * @param string $transform Optional. How to transform the return value. 
  249. * Accepts 'raw' (default) or 'replace-tokens'. 
  250. * @return string HTML or plaintext, depending on $content_type. 
  251. */ 
  252. public function get_content( $transform = 'raw' ) { 
  253. return $this->get( 'content', $transform ); 
  254.  
  255. /** 
  256. * Get the email content (in HTML). 
  257. * Unlike most other methods in this class, this one is not chainable. 
  258. * @since 2.5.0 
  259. * @param string $transform Optional. How to transform the return value. 
  260. * Accepts 'raw' (default) or 'replace-tokens'. 
  261. * @return string HTML email content. 
  262. */ 
  263. public function get_content_html( $transform = 'raw' ) { 
  264. return $this->get( 'content_html', $transform ); 
  265.  
  266. /** 
  267. * Get the email content (in plaintext). 
  268. * Unlike most other methods in this class, this one is not chainable. 
  269. * @since 2.5.0 
  270. * @param string $transform Optional. How to transform the return value. 
  271. * Accepts 'raw' (default) or 'replace-tokens'. 
  272. * @return string Plain text email content. 
  273. */ 
  274. public function get_content_plaintext( $transform = 'raw' ) { 
  275. return $this->get( 'content_plaintext', $transform ); 
  276.  
  277. /** 
  278. * Get the email content type (HTML or plain text) that the email will be sent in. 
  279. * Unlike most other methods in this class, this one is not chainable. 
  280. * @since 2.5.0 
  281. * @param string $transform Optional. How to transform the return value. 
  282. * Accepts 'raw' (default) or 'replace-tokens'. 
  283. * @return string Email content type ("html" or "plaintext"). 
  284. */ 
  285. public function get_content_type( $transform = 'raw' ) { 
  286. return $this->get( 'content_type', $transform ); 
  287.  
  288. /** 
  289. * Get the email's "from" address and name. 
  290. * Unlike most other methods in this class, this one is not chainable. 
  291. * @since 2.5.0 
  292. * @param string $transform Optional. How to transform the return value. 
  293. * Accepts 'raw' (default) or 'replace-tokens'. 
  294. * @return BP_Email_Recipient "From" recipient. 
  295. */ 
  296. public function get_from( $transform = 'raw' ) { 
  297. return $this->get( 'from', $transform ); 
  298.  
  299. /** 
  300. * Get the Post associated with the email. 
  301. * Unlike most other methods in this class, this one is not chainable. 
  302. * @since 2.5.0 
  303. * @return WP_Post The post. 
  304. */ 
  305. public function get_post_object( $transform = 'raw' ) { 
  306. return $this->get( 'post_object', $transform ); 
  307.  
  308. /** 
  309. * Get the email's "reply to" address and name. 
  310. * Unlike most other methods in this class, this one is not chainable. 
  311. * @since 2.5.0 
  312. * @param string $transform Optional. How to transform the return value. 
  313. * Accepts 'raw' (default) or 'replace-tokens'. 
  314. * @return BP_Email_Recipient "Reply to" recipient. 
  315. */ 
  316. public function get_reply_to( $transform = 'raw' ) { 
  317. return $this->get( 'reply_to', $transform ); 
  318.  
  319. /** 
  320. * Get the email subject. 
  321. * Unlike most other methods in this class, this one is not chainable. 
  322. * @since 2.5.0 
  323. * @param string $transform Optional. How to transform the return value. 
  324. * Accepts 'raw' (default) or 'replace-tokens'. 
  325. * @return string Email subject. 
  326. */ 
  327. public function get_subject( $transform = 'raw' ) { 
  328. return $this->get( 'subject', $transform ); 
  329.  
  330. /** 
  331. * Get the email template (the HTML wrapper around the email content). 
  332. * Unlike most other methods in this class, this one is not chainable. 
  333. * @since 2.5.0 
  334. * @param string $transform Optional. How to transform the return value. 
  335. * Accepts 'raw' (default) or 'replace-tokens'. 
  336. * @return string Email template. Assumed to be HTML. 
  337. */ 
  338. public function get_template( $transform = 'raw' ) { 
  339. return $this->get( 'template', $transform ); 
  340.  
  341. /** 
  342. * Get the email's "to" address and name. 
  343. * Unlike most other methods in this class, this one is not chainable. 
  344. * @since 2.5.0 
  345. * @param string $transform Optional. How to transform the return value. 
  346. * Accepts 'raw' (default) or 'replace-tokens'. 
  347. * @return BP_Email_Recipient[] "To" recipients. 
  348. */ 
  349. public function get_to( $transform = 'raw' ) { 
  350. return $this->get( 'to', $transform ); 
  351.  
  352. /** 
  353. * Get token names and replacement values for this email. 
  354. * Unlike most other methods in this class, this one is not chainable. 
  355. * @since 2.5.0 
  356. * @param string $transform Optional. How to transform the return value. 
  357. * Accepts 'raw' (default) or 'replace-tokens'. 
  358. * @return string[] Associative pairing of token name (key) and replacement value (value). 
  359. */ 
  360. public function get_tokens( $transform = 'raw' ) { 
  361. return $this->get( 'tokens', $transform ); 
  362.  
  363. /** 
  364. * Set email headers. 
  365. * Does NOT let you override to/from, etc. Use the methods provided to set those. 
  366. * @since 2.5.0 
  367. * @param string[] $headers Key/value pairs of header name/values (strings). 
  368. * @return BP_Email 
  369. */ 
  370. public function set_headers( array $headers ) { 
  371. $new_headers = array(); 
  372.  
  373. foreach ( $headers as $name => $content ) { 
  374. $content = str_replace( ':', '', $content ); 
  375. $name = str_replace( ':', '', $name ); 
  376.  
  377. $new_headers[ sanitize_key( $name ) ] = sanitize_text_field( $content ); 
  378.  
  379. /** 
  380. * Filters the new value of the email's "headers" property. 
  381. * @since 2.5.0 
  382. * @param string[] $new_headers Key/value pairs of new header name/values (strings). 
  383. * @param BP_Email $this Current instance of the email type class. 
  384. */ 
  385. $this->headers = apply_filters( 'bp_email_set_headers', $new_headers, $this ); 
  386.  
  387. return $this; 
  388.  
  389. /** 
  390. * Set the email's "bcc" address and name. 
  391. * To set a single address, the first parameter is the address and the second the name. 
  392. * You can also pass a user ID or a WP_User object. 
  393. * To set multiple addresses, for each array item, the key is the email address and 
  394. * the value is the name. 
  395. * @since 2.5.0 
  396. * @param string|array|int|WP_User $bcc_address Either a email address, user ID, WP_User object,  
  397. * or an array containing any combination of the above. 
  398. * @param string $name Optional. If $bcc_address is a string, this is the recipient's name. 
  399. * @param string $operation Optional. If "replace", $to_address replaces current setting (default). 
  400. * If "add", $to_address is added to the current setting. 
  401. * @return BP_Email 
  402. */ 
  403. public function set_bcc( $bcc_address, $name = '', $operation = 'replace' ) { 
  404. $bcc = ( $operation !== 'replace' ) ? $this->bcc : array(); 
  405.  
  406. if ( is_array( $bcc_address ) ) { 
  407. foreach ( $bcc_address as $address ) { 
  408. $bcc[] = new BP_Email_Recipient( $address ); 
  409.  
  410. } else { 
  411. $bcc[] = new BP_Email_Recipient( $bcc_address, $name ); 
  412.  
  413. /** 
  414. * Filters the new value of the email's "BCC" property. 
  415. * @since 2.5.0 
  416. * @param BP_Email_Recipient[] $bcc BCC recipients. 
  417. * @param string|array|int|WP_User $bcc_address Either a email address, user ID, WP_User object,  
  418. * or an array containing any combination of the above. 
  419. * @param string $name Optional. If $bcc_address is a string, this is the recipient's name. 
  420. * @param string $operation If "replace", $to_address replaced previous recipients. If "add",  
  421. * $to_address was added to the array of recipients. 
  422. * @param BP_Email $this Current instance of the email type class. 
  423. */ 
  424. $this->bcc = apply_filters( 'bp_email_set_bcc', $bcc, $bcc_address, $name, $operation, $this ); 
  425.  
  426. return $this; 
  427.  
  428. /** 
  429. * Set the email's "cc" address and name. 
  430. * To set a single address, the first parameter is the address and the second the name. 
  431. * You can also pass a user ID or a WP_User object. 
  432. * To set multiple addresses, for each array item, the key is the email address and 
  433. * the value is the name. 
  434. * @since 2.5.0 
  435. * @param string|array|int|WP_User $cc_address Either a email address, user ID, WP_User object,  
  436. * or an array containing any combination of the above. 
  437. * @param string $name Optional. If $cc_address is a string, this is the recipient's name. 
  438. * @param string $operation Optional. If "replace", $to_address replaces current setting (default). 
  439. * If "add", $to_address is added to the current setting. 
  440. * @return BP_Email 
  441. */ 
  442. public function set_cc( $cc_address, $name = '', $operation = 'replace' ) { 
  443. $cc = ( $operation !== 'replace' ) ? $this->cc : array(); 
  444.  
  445. if ( is_array( $cc_address ) ) { 
  446. foreach ( $cc_address as $address ) { 
  447. $cc[] = new BP_Email_Recipient( $address ); 
  448.  
  449. } else { 
  450. $cc[] = new BP_Email_Recipient( $cc_address, $name ); 
  451.  
  452. /** 
  453. * Filters the new value of the email's "CC" property. 
  454. * @since 2.5.0 
  455. * @param BP_Email_Recipient[] $cc CC recipients. 
  456. * @param string|array|int|WP_User $cc_address Either a email address, user ID, WP_User object,  
  457. * or an array containing any combination of the above. 
  458. * @param string $name Optional. If $cc_address is a string, this is the recipient's name. 
  459. * @param string $operation If "replace", $to_address replaced previous recipients. If "add",  
  460. * $to_address was added to the array of recipients. 
  461. * @param BP_Email $this Current instance of the email type class. 
  462. */ 
  463. $this->cc = apply_filters( 'bp_email_set_cc', $cc, $cc_address, $name, $operation, $this ); 
  464.  
  465. return $this; 
  466.  
  467. /** 
  468. * Set the email content (HTML). 
  469. * @since 2.5.0 
  470. * @param string $content HTML email content. 
  471. * @return BP_Email 
  472. */ 
  473. public function set_content_html( $content ) { 
  474.  
  475. /** 
  476. * Filters the new value of the email's "content" property (HTML). 
  477. * @since 2.5.0 
  478. * @param string $content HTML email content. 
  479. * @param BP_Email $this Current instance of the email type class. 
  480. */ 
  481. $this->content_html = apply_filters( 'bp_email_set_content_html', $content, $this ); 
  482.  
  483. return $this; 
  484.  
  485. /** 
  486. * Set the email content (plain text). 
  487. * @since 2.5.0 
  488. * @param string $content Plain text email content. 
  489. * @return BP_Email 
  490. */ 
  491. public function set_content_plaintext( $content ) { 
  492.  
  493. /** 
  494. * Filters the new value of the email's "content" property (plain text). 
  495. * @since 2.5.0 
  496. * @param string $content Plain text email content. 
  497. * @param BP_Email $this Current instance of the email type class. 
  498. */ 
  499. $this->content_plaintext = apply_filters( 'bp_email_set_content_plaintext', $content, $this ); 
  500.  
  501. return $this; 
  502.  
  503. /** 
  504. * Set the content type (HTML or plain text) to send the email in. 
  505. * @since 2.5.0 
  506. * @param string $content_type Email content type ("html" or "plaintext"). 
  507. * @return BP_Email 
  508. */ 
  509. public function set_content_type( $content_type ) { 
  510. if ( ! in_array( $content_type, array( 'html', 'plaintext', ), true ) ) { 
  511. $class = get_class_vars( get_class() ); 
  512. $content_type = $class['content_type']; 
  513.  
  514. /** 
  515. * Filters the new value of the email's "content type" property. 
  516. * The content type (HTML or plain text) to send the email in. 
  517. * @since 2.5.0 
  518. * @param string $content_type Email content type ("html" or "plaintext"). 
  519. * @param BP_Email $this Current instance of the email type class. 
  520. */ 
  521. $this->content_type = apply_filters( 'bp_email_set_content_type', $content_type, $this ); 
  522.  
  523. return $this; 
  524.  
  525. /** 
  526. * Set the email's "from" address and name. 
  527. * @since 2.5.0 
  528. * @param string|array|int|WP_User $email_address Either a email address, user ID, or WP_User object. 
  529. * @param string $name Optional. If $email_address is a string, this is the recipient's name. 
  530. * @return BP_Email 
  531. */ 
  532. public function set_from( $email_address, $name = '' ) { 
  533. $from = new BP_Email_Recipient( $email_address, $name ); 
  534.  
  535. /** 
  536. * Filters the new value of the email's "from" property. 
  537. * @since 2.5.0 
  538. * @param BP_Email_Recipient $from Sender details. 
  539. * @param string|array|int|WP_User $email_address Either a email address, user ID, or WP_User object. 
  540. * @param string $name Optional. If $email_address is a string, this is the recipient's name. 
  541. * @param BP_Email $this Current instance of the email type class. 
  542. */ 
  543. $this->from = apply_filters( 'bp_email_set_from', $from, $email_address, $name, $this ); 
  544.  
  545. return $this; 
  546.  
  547. /** 
  548. * Set the Post object containing the email content template. 
  549. * Also sets the email's subject, content, and template from the Post, for convenience. 
  550. * @since 2.5.0 
  551. * @param WP_Post $post 
  552. * @return BP_Email 
  553. */ 
  554. public function set_post_object( WP_Post $post ) { 
  555.  
  556. /** 
  557. * Filters the new value of the email's "post object" property. 
  558. * @since 2.5.0 
  559. * @param WP_Post $post A Post. 
  560. * @param BP_Email $this Current instance of the email type class. 
  561. */ 
  562. $this->post_object = apply_filters( 'bp_email_set_post_object', $post, $this ); 
  563.  
  564. if ( is_a( $this->post_object, 'WP_Post' ) ) { 
  565. $this->set_subject( $this->post_object->post_title ) 
  566. ->set_content_html( $this->post_object->post_content ) 
  567. ->set_content_plaintext( $this->post_object->post_excerpt ); 
  568.  
  569. ob_start(); 
  570.  
  571. // Load the template. 
  572. add_filter( 'bp_locate_template_and_load', '__return_true' ); 
  573.  
  574. bp_locate_template( bp_email_get_template( $this->post_object ), true, false ); 
  575.  
  576. remove_filter( 'bp_locate_template_and_load', '__return_true' ); 
  577.  
  578. $this->set_template( ob_get_contents() ); 
  579.  
  580. ob_end_clean(); 
  581.  
  582. return $this; 
  583.  
  584. /** 
  585. * Set the email's "reply to" address and name. 
  586. * @since 2.5.0 
  587. * @param string|array|int|WP_User $email_address Either a email address, user ID, WP_User object,  
  588. * or an array containing any combination of the above. 
  589. * @param string $name Optional. If $email_address is a string, this is the recipient's name. 
  590. * @return BP_Email 
  591. */ 
  592. public function set_reply_to( $email_address, $name = '' ) { 
  593. $reply_to = new BP_Email_Recipient( $email_address, $name ); 
  594.  
  595. /** 
  596. * Filters the new value of the email's "reply to" property. 
  597. * @since 2.5.0 
  598. * @param BP_Email_Recipient $reply_to "Reply to" recipient. 
  599. * @param string|array|int|WP_User $email_address Either a email address, user ID, WP_User object,  
  600. * or an array containing any combination of the above. 
  601. * @param string $name Optional. If $email_address is a string, this is the recipient's name. 
  602. * @param BP_Email $this Current instance of the email type class. 
  603. */ 
  604. $this->reply_to = apply_filters( 'bp_email_set_reply_to', $reply_to, $email_address, $name, $this ); 
  605.  
  606. return $this; 
  607.  
  608. /** 
  609. * Set the email subject. 
  610. * @since 2.5.0 
  611. * @param string $subject Email subject. 
  612. * @return BP_Email 
  613. */ 
  614. public function set_subject( $subject ) { 
  615.  
  616. /** 
  617. * Filters the new value of the subject email property. 
  618. * @since 2.5.0 
  619. * @param string $subject Email subject. 
  620. * @param BP_Email $this Current instance of the email type class. 
  621. */ 
  622. $this->subject = apply_filters( 'bp_email_set_subject', $subject, $this ); 
  623.  
  624. return $this; 
  625.  
  626. /** 
  627. * Set the email template (the HTML wrapper around the email content). 
  628. * This needs to include the string "{{{content}}}" to have the post content added 
  629. * when the email template is rendered. 
  630. * @since 2.5.0 
  631. * @param string $template Email template. Assumed to be HTML. 
  632. * @return BP_Email 
  633. */ 
  634. public function set_template( $template ) { 
  635.  
  636. /** 
  637. * Filters the new value of the template email property. 
  638. * @since 2.5.0 
  639. * @param string $template Email template. Assumed to be HTML. 
  640. * @param BP_Email $this Current instance of the email type class. 
  641. */ 
  642. $this->template = apply_filters( 'bp_email_set_template', $template, $this ); 
  643.  
  644. return $this; 
  645.  
  646. /** 
  647. * Set the email's "to" address and name. 
  648. * IMPORTANT NOTE: the assumption with all emails sent by (and belonging to) BuddyPress itself 
  649. * is that there will only be a single `$to_address`. This is to simplify token and templating 
  650. * logic (for example, if multiple recipients, the "unsubscribe" link in the emails will all 
  651. * only link to the first recipient). 
  652. * To set a single address, the first parameter is the address and the second the name. 
  653. * You can also pass a user ID or a WP_User object. 
  654. * To set multiple addresses, for each array item, the key is the email address and 
  655. * the value is the name. 
  656. * @since 2.5.0 
  657. * @param string|array|int|WP_User $to_address Either a email address, user ID, WP_User object,  
  658. * or an array containing any combination of the above. 
  659. * @param string $name Optional. If $to_address is a string, this is the recipient's name. 
  660. * @param string $operation Optional. If "replace", $to_address replaces current setting (default). 
  661. * If "add", $to_address is added to the current setting. 
  662. * @return BP_Email 
  663. */ 
  664. public function set_to( $to_address, $name = '', $operation = 'replace' ) { 
  665. $to = ( $operation !== 'replace' ) ? $this->to : array(); 
  666.  
  667. if ( is_array( $to_address ) ) { 
  668. foreach ( $to_address as $address ) { 
  669. $to[] = new BP_Email_Recipient( $address ); 
  670.  
  671. } else { 
  672. $to[] = new BP_Email_Recipient( $to_address, $name ); 
  673.  
  674. /** 
  675. * Filters the new value of the email's "to" property. 
  676. * @since 2.5.0 
  677. * @param BP_Email_Recipient[] "To" recipients. 
  678. * @param string $to_address "To" address. 
  679. * @param string $name "To" name. 
  680. * @param string $operation If "replace", $to_address replaced previous recipients. If "add",  
  681. * $to_address was added to the array of recipients. 
  682. * @param BP_Email $this Current instance of the email type class. 
  683. */ 
  684. $this->to = apply_filters( 'bp_email_set_to', $to, $to_address, $name, $operation, $this ); 
  685.  
  686. return $this; 
  687.  
  688. /** 
  689. * Set token names and replacement values for this email. 
  690. * In templates, tokens are inserted with a Handlebars-like syntax, e.g. `{{token_name}}`. 
  691. * { and } are reserved characters. There's no need to specify these brackets in your token names. 
  692. * @since 2.5.0 
  693. * @param string[] $tokens Associative array, contains key/value pairs of token name/value. 
  694. * Values are a string or a callable function. 
  695. * @return BP_Email 
  696. */ 
  697. public function set_tokens( array $tokens ) { 
  698. $formatted_tokens = array(); 
  699.  
  700. foreach ( $tokens as $name => $value ) { 
  701. $name = str_replace( array( '{', '}' ), '', sanitize_text_field( $name ) ); 
  702. $formatted_tokens[ $name ] = $value; 
  703.  
  704. /** 
  705. * Filters the new value of the email's "tokens" property. 
  706. * @since 2.5.0 
  707. * @param string[] $formatted_tokens Associative pairing of token names (key) 
  708. * and replacement values (value). 
  709. * @param string[] $tokens Associative pairing of unformatted token 
  710. * names (key) and replacement values (value). 
  711. * @param BP_Email $this Current instance of the email type class. 
  712. */ 
  713. $this->tokens = apply_filters( 'bp_email_set_tokens', $formatted_tokens, $tokens, $this ); 
  714.  
  715. return $this; 
  716.  
  717.  
  718. /** 
  719. * Sanitisation and validation logic. 
  720. */ 
  721.  
  722. /** 
  723. * Check that we'd be able to send this email. 
  724. * Unlike most other methods in this class, this one is not chainable. 
  725. * @since 2.5.0 
  726. * @return bool|WP_Error Returns true if validation succesful, else a descriptive WP_Error. 
  727. */ 
  728. public function validate() { 
  729. $retval = true; 
  730.  
  731. // BCC, CC, and token properties are optional. 
  732. if ( 
  733. ! $this->get_from() || 
  734. ! $this->get_to() || 
  735. ! $this->get_subject() || 
  736. ! $this->get_content() || 
  737. ! $this->get_template() 
  738. ) { 
  739. $retval = new WP_Error( 'missing_parameter', __CLASS__, $this ); 
  740.  
  741. /** 
  742. * Filters whether the email passes basic validation checks. 
  743. * @since 2.5.0 
  744. * @param bool|WP_Error $retval Returns true if validation succesful, else a descriptive WP_Error. 
  745. * @param BP_Email $this Current instance of the email type class. 
  746. */ 
  747. return apply_filters( 'bp_email_validate', $retval, $this );