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


Generated: Wed Dec 11 01:01:37 2019 Cross-referenced by PHPXref 0.7.1