| [ Index ] |
PHP Cross Reference of BuddyPress |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Core component classes. 4 * 5 * @package BuddyPress 6 * @subpackage Core 7 */ 8 9 // Exit if accessed directly 10 defined( 'ABSPATH' ) || exit; 11 12 /** 13 * Represents 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 // Set up the `$post` global. 794 global $post; 795 $reset_post = $post; 796 $post = $this->post_object; 797 798 bp_locate_template( bp_email_get_template( $this->post_object ), true, false ); 799 800 // Reset the `$post` global. 801 $post = $reset_post; 802 803 remove_filter( 'bp_locate_template_and_load', '__return_true' ); 804 805 $this->set_template( ob_get_contents() ); 806 807 ob_end_clean(); 808 } 809 810 return $this; 811 } 812 813 /** 814 * Set the email's "reply to" address and name. 815 * 816 * @since 2.5.0 817 * 818 * @param string|array|int|WP_User $email_address Either a email address, user ID, WP_User object, 819 * or an array containing any combination of the above. 820 * @param string $name Optional. If $email_address is a string, this is the recipient's name. 821 * @return BP_Email 822 */ 823 public function set_reply_to( $email_address, $name = '' ) { 824 $reply_to = new BP_Email_Sender(); 825 826 $reply_to->set_address( $email_address ); 827 $reply_to->set_name( $name ); 828 829 /** 830 * Filters the new value of the email's "reply to" property. 831 * 832 * @since 2.5.0 833 * 834 * @param BP_Email_Recipient $reply_to "Reply to" recipient. 835 * @param string|array|int|WP_User $email_address Either a email address, user ID, WP_User object, 836 * or an array containing any combination of the above. 837 * @param string $name Optional. If $email_address is a string, this is the recipient's name. 838 * @param BP_Email $this Current instance of the email type class. 839 */ 840 $this->reply_to = apply_filters( 'bp_email_set_reply_to', $reply_to, $email_address, $name, $this ); 841 842 return $this; 843 } 844 845 /** 846 * Set the email subject. 847 * 848 * @since 2.5.0 849 * 850 * @param string $subject Email subject. 851 * @return BP_Email 852 */ 853 public function set_subject( $subject ) { 854 855 /** 856 * Filters the new value of the subject email property. 857 * 858 * @since 2.5.0 859 * 860 * @param string $subject Email subject. 861 * @param BP_Email $this Current instance of the email type class. 862 */ 863 $this->subject = apply_filters( 'bp_email_set_subject', $subject, $this ); 864 865 return $this; 866 } 867 868 /** 869 * Set the email template (the HTML wrapper around the email content). 870 * 871 * This needs to include the string "{{{content}}}" to have the post content added 872 * when the email template is rendered. 873 * 874 * @since 2.5.0 875 * 876 * @param string $template Email template. Assumed to be HTML. 877 * @return BP_Email 878 */ 879 public function set_template( $template ) { 880 881 /** 882 * Filters the new value of the template email property. 883 * 884 * @since 2.5.0 885 * 886 * @param string $template Email template. Assumed to be HTML. 887 * @param BP_Email $this Current instance of the email type class. 888 */ 889 $this->template = apply_filters( 'bp_email_set_template', $template, $this ); 890 891 return $this; 892 } 893 894 /** 895 * Set the email's "to" address and name. 896 * 897 * IMPORTANT NOTE: the assumption with all emails sent by (and belonging to) BuddyPress itself 898 * is that there will only be a single `$to_address`. This is to simplify token and templating 899 * logic (for example, if multiple recipients, the "unsubscribe" link in the emails will all 900 * only link to the first recipient). 901 * 902 * To set a single address, the first parameter is the address and the second the name. 903 * You can also pass a user ID or a WP_User object. 904 * 905 * To set multiple addresses, for each array item, the key is the email address and 906 * the value is the name. 907 * 908 * @since 2.5.0 909 * 910 * @param string|array|int|WP_User $to_address Either a email address, user ID, WP_User object, 911 * or an array containing any combination of the above. 912 * @param string $name Optional. If $to_address is a string, this is the recipient's name. 913 * @param string $operation Optional. If "replace", $to_address replaces current setting (default). 914 * If "add", $to_address is added to the current setting. 915 * @return BP_Email 916 */ 917 public function set_to( $to_address, $name = '', $operation = 'replace' ) { 918 $to = ( $operation !== 'replace' ) ? $this->to : array(); 919 920 if ( is_array( $to_address ) ) { 921 foreach ( $to_address as $address ) { 922 $to[] = new BP_Email_Recipient( $address ); 923 } 924 925 } else { 926 $to[] = new BP_Email_Recipient( $to_address, $name ); 927 } 928 929 /** 930 * Filters the new value of the email's "to" property. 931 * 932 * @since 2.5.0 933 * 934 * @param BP_Email_Recipient[] "To" recipients. 935 * @param string $to_address "To" address. 936 * @param string $name "To" name. 937 * @param string $operation If "replace", $to_address replaced previous recipients. If "add", 938 * $to_address was added to the array of recipients. 939 * @param BP_Email $this Current instance of the email type class. 940 */ 941 $this->to = apply_filters( 'bp_email_set_to', $to, $to_address, $name, $operation, $this ); 942 943 return $this; 944 } 945 946 /** 947 * Set token names and replacement values for this email. 948 * 949 * In templates, tokens are inserted with a Handlebars-like syntax, e.g. `{{token_name}}`. 950 * { and } are reserved characters. There's no need to specify these brackets in your token names. 951 * 952 * @since 2.5.0 953 * 954 * @param string[] $tokens Associative array, contains key/value pairs of token name/value. 955 * Values are a string or a callable function. 956 * @return BP_Email 957 */ 958 public function set_tokens( array $tokens ) { 959 $formatted_tokens = array(); 960 961 foreach ( $tokens as $name => $value ) { 962 $name = str_replace( array( '{', '}' ), '', sanitize_text_field( $name ) ); 963 $formatted_tokens[ $name ] = $value; 964 } 965 966 /** 967 * Filters the new value of the email's "tokens" property. 968 * 969 * @since 2.5.0 970 * 971 * @param string[] $formatted_tokens Associative pairing of token names (key) 972 * and replacement values (value). 973 * @param string[] $tokens Associative pairing of unformatted token 974 * names (key) and replacement values (value). 975 * @param BP_Email $this Current instance of the email type class. 976 */ 977 $this->tokens = apply_filters( 'bp_email_set_tokens', $formatted_tokens, $tokens, $this ); 978 979 return $this; 980 } 981 982 983 /* 984 * Sanitisation and validation logic. 985 */ 986 987 /** 988 * Check that we'd be able to send this email. 989 * 990 * Unlike most other methods in this class, this one is not chainable. 991 * 992 * @since 2.5.0 993 * 994 * @return bool|WP_Error Returns true if validation succesful, else a descriptive WP_Error. 995 */ 996 public function validate() { 997 $retval = true; 998 999 // BCC, CC, and token properties are optional. 1000 if ( 1001 ! $this->get_from() || 1002 ! $this->get_to() || 1003 ! $this->get_subject() || 1004 ! $this->get_content() || 1005 ! $this->get_template() 1006 ) { 1007 $retval = new WP_Error( 'missing_parameter', __CLASS__, $this ); 1008 } 1009 1010 // Has the user opted out of receiving any email from this site? 1011 $recipient_to = $this->get_to(); 1012 $recipient_to_first = array_shift( $recipient_to ); 1013 $recipient_address = $recipient_to_first->get_address(); 1014 if ( bp_user_has_opted_out( $recipient_address ) ) { 1015 $retval = new WP_Error( 'user_has_opted_out', __( 'The email recipient has opted out from receiving communication from this site.', 'buddypress' ), $recipient_address ); 1016 } 1017 1018 /** 1019 * Filters whether the email passes basic validation checks. 1020 * 1021 * @since 2.5.0 1022 * 1023 * @param bool|WP_Error $retval Returns true if validation succesful, else a descriptive WP_Error. 1024 * @param BP_Email $this Current instance of the email type class. 1025 */ 1026 return apply_filters( 'bp_email_validate', $retval, $this ); 1027 } 1028 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Sun Dec 22 01:00:54 2024 | Cross-referenced by PHPXref 0.7.1 |