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