[ 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          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  }


Generated: Mon Apr 19 01:01:38 2021 Cross-referenced by PHPXref 0.7.1