[ Index ]

PHP Cross Reference of BuddyPress

title

Body

[close]

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

   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  }


Generated: Tue Oct 27 01:01:40 2020 Cross-referenced by PHPXref 0.7.1