| [ Index ] |
PHP Cross Reference of BuddyPress |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Core invitations class. 4 * 5 * @package BuddyPress 6 * @subpackage Core 7 * @since 5.0.0 8 */ 9 10 // Exit if accessed directly. 11 defined( 'ABSPATH' ) || exit; 12 13 /** 14 * BP Invitations class. 15 * 16 * Extend it to manage your class's invitations. 17 * Your extension class, must, at a minimum, provide the 18 * run_send_action() and run_acceptance_action() methods. 19 * 20 * @since 5.0.0 21 */ 22 abstract class BP_Invitation_Manager { 23 24 /** 25 * The name of the related class. 26 * 27 * @since 5.0.0 28 * @access public 29 * @var string 30 */ 31 protected $class_name; 32 33 /** 34 * Construct parameters. 35 * 36 * @since 5.0.0 37 * 38 * @param array|string $args { 39 * } 40 */ 41 public function __construct( $args = array() ) { 42 $this->class_name = get_class( $this ); 43 } 44 45 /** 46 * Get the invitations table name. 47 * 48 * @since 5.0.0 49 * @access public 50 * @return string 51 */ 52 public static function get_table_name() { 53 return buddypress()->members->table_name_invitations; 54 } 55 56 /** Create ********************************************************************/ 57 58 /** 59 * Add an invitation to a specific user, from a specific user, related to a 60 * specific class. 61 * 62 * @since 5.0.0 63 * 64 * @param array $args { 65 * Array of arguments describing the invitation. All are optional. 66 * @type int $user_id ID of the invited user. 67 * @type int $inviter_id ID of the user who created the invitation. 68 * @type string $invitee_email Email address of the invited user. 69 * @type int $item_id ID associated with the invitation and class. 70 * @type int $secondary_item_id Secondary ID associated with the 71 * invitation and class. 72 * @type string $type Type of record this is: 'invite' or 'request'. 73 * @type string $content Extra information provided by the requester 74 * or inviter. 75 * @type string $date_modified Date the invitation was last modified. 76 * @type int $send_invite Should the invitation also be sent, or is it a 77 * draft invite? 78 * } 79 * @return int|bool ID of the newly created invitation on success, false 80 * on failure. 81 */ 82 public function add_invitation( $args = array() ) { 83 84 $r = bp_parse_args( $args, array( 85 'user_id' => 0, 86 'invitee_email' => '', 87 'inviter_id' => 0, 88 'item_id' => 0, 89 'secondary_item_id' => 0, 90 'type' => 'invite', 91 'content' => '', 92 'date_modified' => bp_core_current_time(), 93 'send_invite' => 0, 94 'accepted' => 0 95 ), 'add_invitation' ); 96 97 // Invitations must have an invitee and inviter. 98 if ( ! ( ( $r['user_id'] || $r['invitee_email'] ) && $r['inviter_id'] ) ) { 99 return false; 100 } 101 102 /** 103 * Is this user allowed to extend invitations in this situation? 104 * 105 * @since 5.0.0 106 * 107 * @param array $r Describes the invitation to be added. 108 */ 109 if ( ! $this->allow_invitation( $r ) ) { 110 return false; 111 } 112 113 // Avoid creating duplicate invitations. 114 $invite_id = $this->invitation_exists( array( 115 'user_id' => $r['user_id'], 116 'invitee_email' => $r['invitee_email'], 117 'inviter_id' => $r['inviter_id'], 118 'item_id' => $r['item_id'], 119 'secondary_item_id' => $r['secondary_item_id'], 120 ) ); 121 122 if ( ! $invite_id ) { 123 // Set up the new invitation as a draft. 124 $invitation = new BP_Invitation; 125 $invitation->user_id = $r['user_id']; 126 $invitation->inviter_id = $r['inviter_id']; 127 $invitation->invitee_email = $r['invitee_email']; 128 $invitation->class = $this->class_name; 129 $invitation->item_id = $r['item_id']; 130 $invitation->secondary_item_id = $r['secondary_item_id']; 131 $invitation->type = $r['type']; 132 $invitation->content = $r['content']; 133 $invitation->date_modified = $r['date_modified']; 134 $invitation->invite_sent = 0; 135 $invitation->accepted = 0; 136 137 $invite_id = $invitation->save(); 138 } 139 140 // "Send" the invite if necessary. 141 if ( $invite_id && $r['send_invite'] ) { 142 $sent = $this->send_invitation_by_id( $invite_id, $r ); 143 if ( ! $sent ) { 144 return false; 145 } 146 } 147 148 return $invite_id; 149 } 150 151 /** 152 * Send an invitation notification. 153 * 154 * @since 5.0.0 155 * @access public 156 * 157 * @param int $invitation_id ID of invitation to send. 158 * @param array $args See BP_Invitation::mark_sent(). 159 * 160 * @return int|bool The number of rows updated, or false on error. 161 */ 162 public function send_invitation_by_id( $invitation_id = 0, $args = array() ) { 163 $updated = false; 164 165 $invitation = new BP_Invitation( $invitation_id ); 166 167 if ( ! $invitation->id ) { 168 return false; 169 } 170 171 /** 172 * Fires before an invitation is sent. 173 * 174 * @since 5.0.0 175 * 176 * @param BP_Invitation object $invitation Invitation about to be sent. 177 */ 178 do_action( 'bp_invitations_send_invitation_by_id_before_send', $invitation ); 179 180 /* 181 * Before sending an invitation, check for outstanding requests to the same item. 182 * A sent invitation + a request = acceptance. 183 */ 184 $request_args = array( 185 'user_id' => $invitation->user_id, 186 'invitee_email' => $invitation->invitee_email, 187 'item_id' => $invitation->item_id, 188 'secondary_item_id' => $invitation->secondary_item_id, 189 ); 190 $request = $this->request_exists( $request_args ); 191 192 if ( ! empty( $request ) ) { 193 // Accept the request. 194 return $this->accept_request( $request_args ); 195 } 196 197 // Perform the send action. 198 $this->run_send_action( $invitation ); 199 200 $updated = BP_Invitation::mark_sent( $invitation->id, $args ); 201 202 return $updated; 203 } 204 205 /** 206 * Add a request to an item for a specific user, related to a 207 * specific class. 208 * 209 * @since 5.0.0 210 * 211 * @param array $args { 212 * Array of arguments describing the invitation. All are optional. 213 * @type int $user_id ID of the invited user. 214 * @type int $inviter_id ID of the user who created the invitation. 215 * @type string $class Name of the invitations class. 216 * @type int $item_id ID associated with the invitation and class. 217 * @type int $secondary_item_id secondary ID associated with the 218 * invitation and class. 219 * @type string $type @TODO. < missing description. 220 * @type string $content Extra information provided by the requester 221 * or inviter. 222 * @type string $date_modified Date the invitation was last modified. 223 * @type int $invite_sent Has the invitation been sent, or is it a 224 * draft invite? 225 * } 226 * @return int|bool ID of the newly created invitation on success, false 227 * on failure. 228 */ 229 public function add_request( $args = array() ) { 230 231 $r = bp_parse_args( $args, array( 232 'user_id' => 0, 233 'inviter_id' => 0, 234 'invitee_email' => '', 235 'item_id' => 0, 236 'secondary_item_id' => 0, 237 'type' => 'request', 238 'content' => '', 239 'date_modified' => bp_core_current_time(), 240 'invite_sent' => 0, 241 'accepted' => 0 242 ), 'add_request' ); 243 244 // If there is no invitee, bail. 245 if ( ! ( $r['user_id'] || $r['invitee_email'] ) ) { 246 return false; 247 } 248 249 /** 250 * Is this user allowed to make a request in this situation? 251 * 252 * @since 5.0.0 253 * 254 * @param array $r Describes the invitation to be added. 255 */ 256 if ( ! $this->allow_request( $r ) ) { 257 return false; 258 } 259 260 /* 261 * Avoid creating duplicate requests. 262 */ 263 $base_args = array( 264 'user_id' => $r['user_id'], 265 'invitee_email' => $r['invitee_email'], 266 'item_id' => $r['item_id'], 267 'secondary_item_id' => $r['secondary_item_id'], 268 ); 269 if ( $this->request_exists( $base_args ) ) { 270 return false; 271 } 272 273 /* 274 * Check for outstanding invitations to the same item. 275 * A request + a sent invite = acceptance. 276 */ 277 $invite_args = array_merge( $base_args, array( 'invite_sent' => 'sent' ) ); 278 $invite = $this->invitation_exists( $invite_args ); 279 280 if ( $invite ) { 281 // Accept the invite. 282 return $this->accept_invitation( $base_args ); 283 } else { 284 // Set up the new request. 285 $request = new BP_Invitation; 286 $request->user_id = $r['user_id']; 287 $request->inviter_id = $r['inviter_id']; 288 $request->invitee_email = $r['invitee_email']; 289 $request->class = $this->class_name; 290 $request->item_id = $r['item_id']; 291 $request->secondary_item_id = $r['secondary_item_id']; 292 $request->type = $r['type']; 293 $request->content = $r['content']; 294 $request->date_modified = $r['date_modified']; 295 $request->invite_sent = $r['invite_sent']; 296 $request->accepted = $r['accepted']; 297 298 // Save the new invitation. 299 return $request->save(); 300 } 301 } 302 303 /** 304 * Send a request notification. 305 * 306 * @since 5.0.0 307 * @access public 308 * 309 * @param int $request_id ID of request to send. 310 * @param array $args See BP_Invitation::mark_sent(). 311 * 312 * @return int|bool The number of rows updated, or false on error. 313 */ 314 public function send_request_notification_by_id( $request_id = 0, $args = array() ) { 315 $updated = false; 316 317 $request = new BP_Invitation( $request_id ); 318 319 if ( ! $request->id ) { 320 return false; 321 } 322 323 // Different uses may need different actions on sending. Plugins can hook in here to perform their own tasks. 324 do_action( 'bp_invitations_send_request_notification_by_id_before_send', $request_id, $request ); 325 326 /* 327 * Before sending notifications, check for outstanding invitations to the same item. 328 * A sent invitation + a request = acceptance. 329 */ 330 $invite_args = array( 331 'user_id' => $request->user_id, 332 'invitee_email' => $request->invitee_email, 333 'item_id' => $request->item_id, 334 'secondary_item_id' => $request->secondary_item_id, 335 'invite_sent' => 'sent' 336 ); 337 $invites = $this->invitation_exists( $invite_args ); 338 339 if ( ! empty( $invites ) ) { 340 // Accept the request. 341 return $this->accept_invitation( $invite_args ); 342 } 343 344 // Perform the send action. 345 $this->run_send_action( $request ); 346 347 $updated = BP_Invitation::mark_sent( $request->id, $args ); 348 349 return $updated; 350 } 351 352 /** Retrieve ******************************************************************/ 353 354 /** 355 * Get a specific invitation by its ID. 356 * 357 * @since 5.0.0 358 * 359 * @param int $id ID of the invitation. 360 * @return BP_Invitation object 361 */ 362 public function get_by_id( $id = 0 ) { 363 return new BP_Invitation( $id ); 364 } 365 366 /** 367 * Get invitations, based on provided filter parameters. 368 * 369 * @since 5.0.0 370 * 371 * @see BP_Invitation::get() for a description of accepted parameters. 372 * 373 * @return array Located invitations. 374 */ 375 public function get_invitations( $args = array() ) { 376 // Default to returning invitations, not requests. 377 if ( empty( $args['type'] ) ) { 378 $args['type'] = 'invite'; 379 } 380 // Use the class_name property value. 381 $args['class'] = $this->class_name; 382 383 return BP_Invitation::get( $args ); 384 } 385 386 /** 387 * Get requests, based on provided filter parameters. 388 * 389 * @since 5.0.0 390 * 391 * @see BP_Invitation::get() for a description of accepted parameters. 392 * 393 * @return array Located invitations. 394 */ 395 public function get_requests( $args = array() ) { 396 // Set request-specific parameters. 397 $args['type'] = 'request'; 398 $args['inviter_id'] = false; 399 $args['invite_sent'] = 'all'; 400 401 // Use the class_name property value. 402 $args['class'] = $this->class_name; 403 404 return BP_Invitation::get( $args ); 405 } 406 407 /** 408 * Check whether an invitation exists matching the passed arguments. 409 * 410 * @since 5.0.0 411 * 412 * @see BP_Invitation::get() for a description of accepted parameters. 413 * 414 * @return int|bool ID of first found invitation or false if none found. 415 */ 416 public function invitation_exists( $args = array() ) { 417 $is_invited = false; 418 419 $args['fields'] = 'ids'; 420 $invites = $this->get_invitations( $args ); 421 if ( $invites ) { 422 $is_invited = current( $invites ); 423 } 424 return $is_invited; 425 } 426 427 /** 428 * Check whether a request exists matching the passed arguments. 429 * 430 * @since 5.0.0 431 * 432 * @see BP_Invitation::get() for a description of accepted parameters. 433 * 434 * @return int|bool ID of existing request or false if none found. 435 */ 436 public function request_exists( $args = array() ) { 437 $has_request = false; 438 439 $args['fields'] = 'ids'; 440 $requests = $this->get_requests( $args ); 441 if ( $requests ) { 442 $has_request = current( $requests ); 443 } 444 return $has_request; 445 } 446 447 /** Update ********************************************************************/ 448 449 /** 450 * Accept invitation, based on provided filter parameters. 451 * 452 * @since 5.0.0 453 * 454 * @see BP_Invitation::get() for a description of 455 * accepted update/where arguments. 456 * 457 * @param array $args { 458 * Invitation characteristics. Some basic info is required to accept an invitation, 459 * because we'll need to accept all similar invitations and requests. 460 * 461 * @type int $user_id User ID of the invitee. 462 * Either 'user_id' or 'invitee_email' is required. 463 * @type string $invitee_email Email address of the invitee. 464 * Either 'user_id' or 'invitee_email' is required. 465 * @type int $item_id Item ID of the invitation to accept. 466 * @type int $secondary_item_id Optional. Secondary item ID if needed. 467 * @type string $invite_sent Optional. Defaults to only allowing the 468 * acceptance of sent invitations. 469 * @type string $date_modified Modified time in 'Y-m-d h:i:s' format, GMT. 470 * Defaults to current time if not specified. 471 * } 472 * 473 * @return int|bool Number of rows updated on success, false on failure. 474 */ 475 public function accept_invitation( $args = array() ) { 476 477 $r = bp_parse_args( $args, array( 478 'user_id' => 0, 479 'invitee_email' => '', 480 'item_id' => null, 481 'secondary_item_id' => null, 482 'invite_sent' => 'sent', 483 'date_modified' => bp_core_current_time(), 484 ), 'accept_invitation' ); 485 $r['class'] = $this->class_name; 486 487 if ( ! ( ( $r['user_id'] || $r['invitee_email'] ) && $r['class'] && $r['item_id'] ) ) { 488 return false; 489 } 490 491 if ( ! $this->invitation_exists( $r ) ) { 492 return false; 493 } 494 495 $success = $this->run_acceptance_action( 'invite', $r ); 496 if ( $success ) { 497 // Mark invitations & requests to this item for this user. 498 $this->mark_accepted( $r ); 499 500 // Allow plugins an opportunity to act on the change. 501 do_action( 'bp_invitations_accepted_invite', $r ); 502 } 503 return $success; 504 } 505 506 /** 507 * Accept invitation, based on provided filter parameters. 508 * 509 * @since 5.0.0 510 * 511 * @see BP_Invitation::get() for a description of 512 * accepted update/where arguments. 513 * 514 * @param array $args { 515 * Invitation characteristics. Some basic info is required to accept an invitation, 516 * because we'll need to accept all similar invitations and requests. 517 * 518 * @type int $user_id User ID of the invitee. 519 * @type int $item_id Item ID of the invitation to accept. 520 * @type int $secondary_item_id Optional. Secondary item ID if needed. 521 * @type string $date_modified Modified time in 'Y-m-d h:i:s' format, GMT. 522 * Defaults to current time if not specified. 523 * } 524 * 525 * @return bool Number of rows updated on success, false on failure. 526 */ 527 public function accept_request( $args = array() ) { 528 529 $r = bp_parse_args( $args, array( 530 'user_id' => 0, 531 'item_id' => null, 532 'secondary_item_id' => null, 533 'date_modified' => bp_core_current_time(), 534 ), 'accept_request' ); 535 $r['class'] = $this->class_name; 536 537 if ( ! ( $r['user_id'] && $r['class'] && $r['item_id'] ) ) { 538 return false; 539 } 540 541 if ( ! $this->request_exists( $r ) ) { 542 return false; 543 } 544 545 $success = $this->run_acceptance_action( 'request', $r ); 546 if ( $success ) { 547 // Update/Delete all related invitations & requests to this item for this user. 548 $this->mark_accepted( $r ); 549 550 // Allow plugins an opportunity to act on the change. 551 do_action( 'bp_invitations_accepted_request', $r ); 552 } 553 return $success; 554 } 555 556 /** 557 * Update invitation, based on provided filter parameters. 558 * 559 * @since 5.0.0 560 * 561 * @see BP_Invitation::get() for a description of 562 * accepted update/where arguments. 563 * 564 * @param array $update_args Associative array of fields to update, 565 * and the values to update them to. Of the format 566 * array( 'user_id' => 4 ) 567 * @param array $where_args Associative array of columns/values, to 568 * determine which invitations should be updated. Formatted as 569 * array( 'item_id' => 7 ) 570 * @return int|bool Number of rows updated on success, false on failure. 571 */ 572 public function update_invitation( $update_args = array(), $where_args = array() ) { 573 $update_args['class'] = $this->class_name; 574 return BP_Invitation::update( $update_args, $where_args ); 575 } 576 577 /** 578 * This is where custom actions are added (in child classes) 579 * to run when an invitation or request needs to be "sent." 580 * 581 * @since 5.0.0 582 * 583 * @param BP_Invitation $invitation The invitation to send. 584 * @return bool True on success, false on failure. 585 */ 586 abstract public function run_send_action( BP_Invitation $invitation ); 587 588 /** 589 * Mark invitations as sent that are found by user_id, inviter_id, 590 * invitee_email, class name, optional item id, 591 * optional secondary item id. 592 * 593 * @since 5.0.0 594 * 595 * @param array $args { 596 * Associative array of arguments. All arguments but $page and 597 * $per_page can be treated as filter values for get_where_sql() 598 * and get_query_clauses(). All items are optional. 599 * @type int|array $user_id ID of user being queried. Can be an 600 * array of user IDs. 601 * @type int|array $inviter_id ID of user who created the 602 * invitation. Can be an array of user IDs. 603 * Special cases 604 * @type string|array $invitee_email Email address of invited users 605 * being queried. Can be an array of addresses. 606 * @type string|array $class Name of the class to 607 * filter by. Can be an array of class names. 608 * @type int|array $item_id ID of associated item. Can be an array 609 * of multiple item IDs. 610 * @type int|array $secondary_item_id ID of secondary associated 611 * item. Can be an array of multiple IDs. 612 * } 613 */ 614 public function mark_sent( $args ) { 615 $args['class'] = $this->class_name; 616 return BP_Invitation::mark_sent_by_data( $args ); 617 } 618 619 /** 620 * This is where custom actions are added (in child classes) 621 * to run when an invitation or request is accepted. 622 * 623 * @since 5.0.0 624 * 625 * @param int $id The ID of the invitation to mark as sent. 626 * @return bool True on success, false on failure. 627 */ 628 abstract public function run_acceptance_action( $type, $r ); 629 630 /** 631 * Mark invitation as accepted by invitation ID. 632 * 633 * @since 5.0.0 634 * 635 * @see BP_Invitation::mark_accepted() 636 * for a description of arguments. 637 * @return bool True on success, false on failure. 638 */ 639 public function mark_accepted_by_id( $id, $args ) { 640 return BP_Invitation::mark_accepted( $id, $args ); 641 } 642 643 /** 644 * Mark invitations as sent that are found by user_id, inviter_id, 645 * invitee_email, class name, item id, and 646 * optional secondary item id. 647 * 648 * @since 5.0.0 649 * 650 * @see BP_Invitation::mark_accepted_by_data() 651 * for a description of arguments. 652 */ 653 public function mark_accepted( $args ) { 654 $args['class'] = $this->class_name; 655 return BP_Invitation::mark_accepted_by_data( $args ); 656 } 657 658 /** Delete ********************************************************************/ 659 660 /** 661 * Delete an invitation or invitations by query data. 662 * 663 * @since 5.0.0 664 * 665 * @see BP_Invitation::delete for a description of arguments. 666 * @return int|bool Number of rows deleted on success, false on failure. 667 */ 668 public function delete( $args ) { 669 if ( empty( $args['type'] ) ) { 670 $args['type'] = 'invite'; 671 } 672 $args['class'] = $this->class_name; 673 return BP_Invitation::delete( $args ); 674 } 675 676 /** 677 * Delete a request or requests by query data. 678 * 679 * @since 5.0.0 680 * 681 * @see BP_Invitation::delete for a description of arguments. 682 * 683 * @return int|bool Number of rows deleted on success, false on failure. 684 */ 685 public function delete_requests( $args ) { 686 $args['type'] = 'request'; 687 return $this->delete( $args ); 688 } 689 690 /** 691 * Delete all invitations by class. 692 * 693 * Used when clearing out invitations for an entire class. Possibly used 694 * when deactivating a component related to a class that created invitations. 695 * 696 * @since 5.0.0 697 * 698 * @return int|bool Number of rows deleted on success, false on failure. 699 */ 700 public function delete_all() { 701 return BP_Invitation::delete( array( 702 'class' => $this->class_name, 703 ) ); 704 } 705 706 /** 707 * This is where custom actions are added (in child classes) 708 * to determine whether an invitation should be allowed. 709 * 710 * @since 5.0.0 711 * 712 * @param array $args The parameters describing the invitation. 713 * @return bool True if allowed, false to end process. 714 */ 715 public function allow_invitation( $args ) { 716 return true; 717 } 718 719 /** 720 * This is where custom actions are added (in child classes) 721 * to determine whether a request should be allowed. 722 * 723 * @since 5.0.0 724 * 725 * @param array $args The parameters describing the request. 726 * @return bool True if allowed, false to end process. 727 */ 728 public function allow_request( $args ) { 729 return true; 730 } 731 732 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Mon Apr 19 01:01:38 2021 | Cross-referenced by PHPXref 0.7.1 |