[ Index ]

PHP Cross Reference of BuddyPress

title

Body

[close]

/src/bp-core/classes/ -> class-bp-email.php (source)

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


Generated: Sat Sep 21 01:01:46 2019 Cross-referenced by PHPXref 0.7.1