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