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