[ Index ]

PHP Cross Reference of BuddyPress

title

Body

[close]

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

   1  <?php
   2  /**
   3   * BuddyPress Invitation Class
   4   *
   5   * @package BuddyPress
   6   * @subpackage Invitations
   7   *
   8   * @since 5.0.0
   9   */
  10  
  11  // Exit if accessed directly.
  12  defined( 'ABSPATH' ) || exit;
  13  
  14  /**
  15   * BuddyPress Invitations.
  16   *
  17   * Use this class to create, access, edit, or delete BuddyPress Invitations.
  18   *
  19   * @since 5.0.0
  20   */
  21  class BP_Invitation {
  22  
  23      /**
  24       * The invitation ID.
  25       *
  26       * @since 5.0.0
  27       * @access public
  28       * @var int
  29       */
  30      public $id;
  31  
  32      /**
  33       * The ID of the invited user.
  34       *
  35       * @since 5.0.0
  36       * @access public
  37       * @var int
  38       */
  39      public $user_id;
  40  
  41      /**
  42       * The ID of the user who created the invitation.
  43       *
  44       * @since 5.0.0
  45       * @access public
  46       * @var int
  47       */
  48      public $inviter_id;
  49  
  50      /**
  51       * The email address of the invited user.
  52       * Used when extending an invitation to someone who does not belong to the site.
  53       *
  54       * @since 5.0.0
  55       * @access public
  56       * @var string
  57       */
  58      public $invitee_email;
  59  
  60      /**
  61       * The name of the related class.
  62       *
  63       * @since 5.0.0
  64       * @access public
  65       * @var string
  66       */
  67      public $class;
  68  
  69      /**
  70       * The ID associated with the invitation and component.
  71       * Example: the group ID if a group invitation
  72       *
  73       * @since 5.0.0
  74       * @access public
  75       * @var int
  76       */
  77      public $item_id;
  78  
  79      /**
  80       * The secondary ID associated with the invitation and component.
  81       * Example: a taxonomy term ID if invited to a site's category-specific RSS feed
  82       *
  83       * @since 5.0.0
  84       * @access public
  85       * @var int
  86       */
  87      public $secondary_item_id = null;
  88  
  89      /**
  90       * Invite or request.
  91       *
  92       * @since 5.0.0
  93       * @access public
  94       * @var string
  95       */
  96      public $type;
  97  
  98      /**
  99       * Extra information provided by the requester or inviter.
 100       *
 101       * @since 5.0.0
 102       * @access public
 103       * @var string
 104       */
 105      public $content;
 106  
 107      /**
 108       * The date the invitation was last modified.
 109       *
 110       * @since 5.0.0
 111       * @access public
 112       * @var string
 113       */
 114      public $date_modified;
 115  
 116      /**
 117       * Has the invitation been sent, or is it a draft invite?
 118       *
 119       * @since 5.0.0
 120       * @access public
 121       * @var bool
 122       */
 123      public $invite_sent;
 124  
 125      /**
 126       * Has the invitation been accepted by the invitee?
 127       *
 128       * @since 5.0.0
 129       * @access public
 130       * @var bool
 131       */
 132      public $accepted;
 133  
 134      /** Public Methods ****************************************************/
 135  
 136      /**
 137       * Constructor method.
 138       *
 139       * @since 5.0.0
 140       *
 141       * @param int $id Optional. Provide an ID to access an existing
 142       *        invitation item.
 143       */
 144  	public function __construct( $id = 0 ) {
 145          if ( ! empty( $id ) ) {
 146              $this->id = (int) $id;
 147              $this->populate();
 148          }
 149      }
 150  
 151      /**
 152       * Update or insert invitation details into the database.
 153       *
 154       * @since 5.0.0
 155       *
 156       * @global wpdb $wpdb WordPress database object.
 157       *
 158       * @return bool True on success, false on failure.
 159       */
 160  	public function save() {
 161  
 162          // Return value
 163          $retval = false;
 164  
 165          // Default data and format
 166          $data = array(
 167              'user_id'           => $this->user_id,
 168              'inviter_id'        => $this->inviter_id,
 169              'invitee_email'     => $this->invitee_email,
 170              'class'             => sanitize_key( $this->class ),
 171              'item_id'           => $this->item_id,
 172              'secondary_item_id' => $this->secondary_item_id,
 173              'type'              => $this->type,
 174              'content'           => wp_kses( wp_unslash( $this->content ), array() ),
 175              'date_modified'     => $this->date_modified,
 176              'invite_sent'       => $this->invite_sent,
 177              'accepted'          => $this->accepted,
 178          );
 179          $data_format = array( '%d', '%d', '%s', '%s', '%d', '%d', '%s', '%s', '%s', '%d', '%d' );
 180  
 181          /**
 182           * Fires before an invitation is saved.
 183           *
 184           * @since 5.0.0
 185           *
 186           * @param BP_Invitation object $this Characteristics of the invitation to be saved.
 187           */
 188          do_action_ref_array( 'bp_invitation_before_save', array( &$this ) );
 189  
 190          // Update.
 191          if ( ! empty( $this->id ) ) {
 192              $result = self::_update( $data, array( 'ID' => $this->id ), $data_format, array( '%d' ) );
 193          // Insert.
 194          } else {
 195              $result = self::_insert( $data, $data_format );
 196          }
 197  
 198          // Set the invitation ID if successful.
 199          if ( ! empty( $result ) && ! is_wp_error( $result ) ) {
 200              global $wpdb;
 201  
 202              $this->id = $wpdb->insert_id;
 203              $retval   = $wpdb->insert_id;
 204          }
 205  
 206          wp_cache_delete( $this->id, 'bp_invitations' );
 207  
 208          /**
 209           * Fires after an invitation is saved.
 210           *
 211           * @since 5.0.0
 212           *
 213           * @param BP_Invitation object $this Characteristics of the invitation just saved.
 214           */
 215          do_action_ref_array( 'bp_invitation_after_save', array( &$this ) );
 216  
 217          // Return the result.
 218          return $retval;
 219      }
 220  
 221      /**
 222       * Fetch data for an existing invitation from the database.
 223       *
 224       * @since 5.0.0
 225       *
 226       * @global BuddyPress $bp The one true BuddyPress instance.
 227       * @global wpdb $wpdb WordPress database object.
 228       */
 229  	public function populate() {
 230          global $wpdb;
 231          $invites_table_name = BP_Invitation_Manager::get_table_name();
 232  
 233          // Check cache for invitation data.
 234          $invitation = wp_cache_get( $this->id, 'bp_invitations' );
 235  
 236          // Cache missed, so query the DB.
 237          if ( false === $invitation ) {
 238              $invitation = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM {$invites_table_name} WHERE id = %d", $this->id ) );
 239              wp_cache_set( $this->id, $invitation,'bp_invitations' );
 240          }
 241  
 242          // No invitation found so set the ID and bail.
 243          if ( empty( $invitation ) || is_wp_error( $invitation ) ) {
 244              $this->id = 0;
 245              return;
 246          }
 247  
 248          $this->user_id           = (int) $invitation->user_id;
 249          $this->inviter_id        = (int) $invitation->inviter_id;
 250          $this->invitee_email     = $invitation->invitee_email;
 251          $this->class             = sanitize_key( $invitation->class );
 252          $this->item_id           = (int) $invitation->item_id;
 253          $this->secondary_item_id = (int) $invitation->secondary_item_id;
 254          $this->type              = $invitation->type;
 255          $this->content           = $invitation->content;
 256          $this->date_modified     = $invitation->date_modified;
 257          $this->invite_sent       = (int) $invitation->invite_sent;
 258          $this->accepted          = (int) $invitation->accepted;
 259  
 260      }
 261  
 262      /** Protected Static Methods ******************************************/
 263  
 264      /**
 265       * Create an invitation entry.
 266       *
 267       * @since 5.0.0
 268       *
 269       * @param array $data {
 270       *     Array of invitation data, passed to {@link wpdb::insert()}.
 271       *       @type int    $user_id           ID of the invited user.
 272       *       @type int    $inviter_id        ID of the user who created the invitation.
 273       *       @type string $invitee_email     Email address of the invited user.
 274       *        @type string $class             Name of the related class.
 275       *        @type int    $item_id           ID associated with the invitation and component.
 276       *        @type int    $secondary_item_id Secondary ID associated with the invitation and
 277       *                                     component.
 278       *        @type string $content           Extra information provided by the requester
 279       *                                       or inviter.
 280       *        @type string $date_modified     Date the invitation was last modified.
 281       *        @type int    $invite_sent       Has the invitation been sent, or is it a draft
 282       *                                     invite?
 283       * }
 284       * @param array $data_format See {@link wpdb::insert()}.
 285       * @return int|false The number of rows inserted, or false on error.
 286       */
 287  	protected static function _insert( $data = array(), $data_format = array() ) {
 288          global $wpdb;
 289          return $wpdb->insert( BP_Invitation_Manager::get_table_name(), $data, $data_format );
 290      }
 291  
 292      /**
 293       * Update invitations.
 294       *
 295       * @since 5.0.0
 296       *
 297       * @see wpdb::update() for further description of paramater formats.
 298       *
 299       * @param array $data         Array of invitation data to update, passed to
 300       *                            {@link wpdb::update()}. Accepts any property of a
 301       *                            BP_Invitation object.
 302       * @param array $where        The WHERE params as passed to wpdb::update().
 303       *                            Typically consists of array( 'ID' => $id ) to specify the ID
 304       *                            of the item being updated. See {@link wpdb::update()}.
 305       * @param array $data_format  See {@link wpdb::insert()}.
 306       * @param array $where_format See {@link wpdb::insert()}.
 307       * @return int|false The number of rows updated, or false on error.
 308       */
 309  	protected static function _update( $data = array(), $where = array(), $data_format = array(), $where_format = array() ) {
 310          global $wpdb;
 311          return $wpdb->update( BP_Invitation_Manager::get_table_name(), $data, $where, $data_format, $where_format );
 312      }
 313  
 314      /**
 315       * Delete invitations.
 316       *
 317       * @since 5.0.0
 318       *
 319       * @see wpdb::update() for further description of paramater formats.
 320       *
 321       * @param array $where        Array of WHERE clauses to filter by, passed to
 322       *                            {@link wpdb::delete()}. Accepts any property of a
 323       *                            BP_Invitation object.
 324       * @param array $where_format See {@link wpdb::insert()}.
 325       * @return int|false The number of rows updated, or false on error.
 326       */
 327  	protected static function _delete( $where = array(), $where_format = array() ) {
 328          global $wpdb;
 329          return $wpdb->delete( BP_Invitation_Manager::get_table_name(), $where, $where_format );
 330      }
 331  
 332      /**
 333       * Assemble the WHERE clause of a get() SQL statement.
 334       *
 335       * Used by BP_Invitation::get() to create its WHERE
 336       * clause.
 337       *
 338       * @since 5.0.0
 339       *
 340       * @param array $args See {@link BP_Invitation::get()} for more details.
 341       * @return string WHERE clause.
 342       */
 343  	protected static function get_where_sql( $args = array() ) {
 344          global $wpdb;
 345  
 346          $where_conditions = array();
 347          $where            = '';
 348  
 349          // id.
 350          if ( false !== $args['id'] ) {
 351              $id_in = implode( ',', wp_parse_id_list( $args['id'] ) );
 352              $where_conditions['id'] = "id IN ({$id_in})";
 353          }
 354  
 355          // user_id.
 356          if ( ! empty( $args['user_id'] ) ) {
 357              $user_id_in = implode( ',', wp_parse_id_list( $args['user_id'] ) );
 358              $where_conditions['user_id'] = "user_id IN ({$user_id_in})";
 359          }
 360  
 361          // inviter_id. 0 can be meaningful, in the case of requests.
 362          if ( ! empty( $args['inviter_id'] ) || 0 === $args['inviter_id'] ) {
 363              $inviter_id_in = implode( ',', wp_parse_id_list( $args['inviter_id'] ) );
 364              $where_conditions['inviter_id'] = "inviter_id IN ({$inviter_id_in})";
 365          }
 366  
 367          // invitee_email.
 368          if ( ! empty( $args['invitee_email'] ) ) {
 369              if ( ! is_array( $args['invitee_email'] ) ) {
 370                  $invitee_emails = explode( ',', $args['invitee_email'] );
 371              } else {
 372                  $invitee_emails = $args['invitee_email'];
 373              }
 374  
 375              $email_clean = array();
 376              foreach ( $invitee_emails as $email ) {
 377                  $email_clean[] = $wpdb->prepare( '%s', $email );
 378              }
 379  
 380              $invitee_email_in = implode( ',', $email_clean );
 381              $where_conditions['invitee_email'] = "invitee_email IN ({$invitee_email_in})";
 382          }
 383  
 384          // class.
 385          if ( ! empty( $args['class'] ) ) {
 386              if ( ! is_array( $args['class'] ) ) {
 387                  $class_names = explode( ',', $args['class'] );
 388              } else {
 389                  $class_names = $args['class'];
 390              }
 391  
 392              $cn_clean = array();
 393              foreach ( $class_names as $cn ) {
 394                  $cn_clean[] = $wpdb->prepare( '%s', sanitize_key( $cn ) );
 395              }
 396  
 397              $cn_in = implode( ',', $cn_clean );
 398              $where_conditions['class'] = "class IN ({$cn_in})";
 399          }
 400  
 401          // item_id.
 402          if ( ! empty( $args['item_id'] ) ) {
 403              $item_id_in = implode( ',', wp_parse_id_list( $args['item_id'] ) );
 404              $where_conditions['item_id'] = "item_id IN ({$item_id_in})";
 405          }
 406  
 407          // secondary_item_id.
 408          if ( ! empty( $args['secondary_item_id'] ) ) {
 409              $secondary_item_id_in = implode( ',', wp_parse_id_list( $args['secondary_item_id'] ) );
 410              $where_conditions['secondary_item_id'] = "secondary_item_id IN ({$secondary_item_id_in})";
 411          }
 412  
 413          // Type.
 414          if ( ! empty( $args['type'] ) && 'all' !== $args['type'] ) {
 415              if ( 'invite' == $args['type'] || 'request' == $args['type'] ) {
 416                  $type_clean = $wpdb->prepare( '%s', $args['type'] );
 417                  $where_conditions['type'] = "type = {$type_clean}";
 418              }
 419          }
 420  
 421          /**
 422           * invite_sent
 423           * Only create a where statement if something less than "all" has been
 424           * specifically requested.
 425           */
 426          if ( ! empty( $args['invite_sent'] ) && 'all' !== $args['invite_sent'] ) {
 427              if ( $args['invite_sent'] == 'draft' ) {
 428                  $where_conditions['invite_sent'] = "invite_sent = 0";
 429              } else if ( $args['invite_sent'] == 'sent' ) {
 430                  $where_conditions['invite_sent'] = "invite_sent = 1";
 431              }
 432          }
 433  
 434          // Accepted.
 435          if ( ! empty( $args['accepted'] ) && 'all' !== $args['accepted'] ) {
 436              if ( $args['accepted'] == 'pending' ) {
 437                  $where_conditions['accepted'] = "accepted = 0";
 438              } else if ( $args['accepted'] == 'accepted' ) {
 439                  $where_conditions['accepted'] = "accepted = 1";
 440              }
 441          }
 442  
 443          // search_terms.
 444          if ( ! empty( $args['search_terms'] ) ) {
 445              $search_terms_like = '%' . bp_esc_like( $args['search_terms'] ) . '%';
 446              $where_conditions['search_terms'] = $wpdb->prepare( '( invitee_email LIKE %s OR content LIKE %s )', $search_terms_like, $search_terms_like );
 447          }
 448  
 449          // Custom WHERE.
 450          if ( ! empty( $where_conditions ) ) {
 451              $where = 'WHERE ' . implode( ' AND ', $where_conditions );
 452          }
 453  
 454          return $where;
 455      }
 456  
 457      /**
 458       * Assemble the ORDER BY clause of a get() SQL statement.
 459       *
 460       * Used by BP_Invitation::get() to create its ORDER BY
 461       * clause.
 462       *
 463       * @since 5.0.0
 464       *
 465       * @param array $args See {@link BP_Invitation::get()} for more details.
 466       * @return string ORDER BY clause.
 467       */
 468  	protected static function get_order_by_sql( $args = array() ) {
 469  
 470          // Setup local variable.
 471          $conditions = array();
 472          $retval     = '';
 473  
 474          // Order by.
 475          if ( ! empty( $args['order_by'] ) ) {
 476              $order_by               = implode( ', ', (array) $args['order_by'] );
 477              $conditions['order_by'] = "{$order_by}";
 478          }
 479  
 480          // Sort order direction.
 481          if ( ! empty( $args['sort_order'] ) ) {
 482              $sort_order               = bp_esc_sql_order( $args['sort_order'] );
 483              $conditions['sort_order'] = "{$sort_order}";
 484          }
 485  
 486          // Custom ORDER BY.
 487          if ( ! empty( $conditions ) ) {
 488              $retval = 'ORDER BY ' . implode( ' ', $conditions );
 489          }
 490  
 491          return $retval;
 492      }
 493  
 494      /**
 495       * Assemble the LIMIT clause of a get() SQL statement.
 496       *
 497       * Used by BP_Invitation::get() to create its LIMIT clause.
 498       *
 499       * @since 5.0.0
 500       *
 501       * @param array $args See {@link BP_Invitation::get()} for more details.
 502       * @return string LIMIT clause.
 503       */
 504  	protected static function get_paged_sql( $args = array() ) {
 505          global $wpdb;
 506  
 507          // Setup local variable.
 508          $retval = '';
 509  
 510          // Custom LIMIT.
 511          if ( ! empty( $args['page'] ) && ! empty( $args['per_page'] ) ) {
 512              $page     = absint( $args['page']     );
 513              $per_page = absint( $args['per_page'] );
 514              $offset   = $per_page * ( $page - 1 );
 515              $retval   = $wpdb->prepare( "LIMIT %d, %d", $offset, $per_page );
 516          }
 517  
 518          return $retval;
 519      }
 520  
 521      /**
 522       * Assemble query clauses, based on arguments, to pass to $wpdb methods.
 523       *
 524       * The insert(), update(), and delete() methods of {@link wpdb} expect
 525       * arguments of the following forms:
 526       *
 527       * - associative arrays whose key/value pairs are column => value, to
 528       *   be used in WHERE, SET, or VALUES clauses
 529       * - arrays of "formats", which tell $wpdb->prepare() which type of
 530       *   value to expect when sanitizing (eg, array( '%s', '%d' ))
 531       *
 532       * This utility method can be used to assemble both kinds of params,
 533       * out of a single set of associative array arguments, such as:
 534       *
 535       *     $args = array(
 536       *         'user_id' => 4,
 537       *         'class'   => 'BP_Groups_Invitation_Manager',
 538       *     );
 539       *
 540       * This will be converted to:
 541       *
 542       *     array(
 543       *         'data' => array(
 544       *             'user_id' => 4,
 545       *             'class'   => 'BP_Groups_Invitation_Manager',
 546       *         ),
 547       *         'format' => array(
 548       *             '%d',
 549       *             '%s',
 550       *         ),
 551       *     )
 552       *
 553       * which can easily be passed as arguments to the $wpdb methods.
 554       *
 555       * @since 5.0.0
 556       *
 557       * @param array $args Associative array of filter arguments.
 558       *                    See {@BP_Invitation::get()} for a breakdown.
 559       * @return array Associative array of 'data' and 'format' args.
 560       */
 561  	protected static function get_query_clauses( $args = array() ) {
 562          $where_clauses = array(
 563              'data'   => array(),
 564              'format' => array(),
 565          );
 566  
 567          // id.
 568          if ( ! empty( $args['id'] ) ) {
 569              $where_clauses['data']['id'] = absint( $args['id'] );
 570              $where_clauses['format'][] = '%d';
 571          }
 572  
 573          // user_id.
 574          if ( ! empty( $args['user_id'] ) ) {
 575              $where_clauses['data']['user_id'] = absint( $args['user_id'] );
 576              $where_clauses['format'][] = '%d';
 577          }
 578  
 579          // inviter_id.
 580          if ( ! empty( $args['inviter_id'] ) ) {
 581              $where_clauses['data']['inviter_id'] = absint( $args['inviter_id'] );
 582              $where_clauses['format'][] = '%d';
 583          }
 584  
 585          // invitee_email.
 586          if ( ! empty( $args['invitee_email'] ) ) {
 587              $where_clauses['data']['invitee_email'] = $args['invitee_email'];
 588              $where_clauses['format'][] = '%s';
 589          }
 590  
 591          // class.
 592          if ( ! empty( $args['class'] ) ) {
 593              $where_clauses['data']['class'] = $args['class'];
 594              $where_clauses['format'][] = '%s';
 595          }
 596  
 597          // item_id.
 598          if ( ! empty( $args['item_id'] ) ) {
 599              $where_clauses['data']['item_id'] = absint( $args['item_id'] );
 600              $where_clauses['format'][] = '%d';
 601          }
 602  
 603          // secondary_item_id.
 604          if ( ! empty( $args['secondary_item_id'] ) ) {
 605              $where_clauses['data']['secondary_item_id'] = absint( $args['secondary_item_id'] );
 606              $where_clauses['format'][] = '%d';
 607          }
 608  
 609          // type.
 610          if ( ! empty( $args['type'] ) && 'all' !== $args['type'] ) {
 611              if ( 'invite' == $args['type'] || 'request' == $args['type'] ) {
 612                  $where_clauses['data']['type'] = $args['type'];
 613                  $where_clauses['format'][] = '%s';
 614              }
 615          }
 616  
 617          /**
 618           * invite_sent
 619           * Only create a where statement if something less than "all" has been
 620           * specifically requested.
 621           */
 622          if ( isset( $args['invite_sent'] ) && 'all' !== $args['invite_sent'] ) {
 623              if ( $args['invite_sent'] == 'draft' ) {
 624                  $where_clauses['data']['invite_sent'] = 0;
 625                  $where_clauses['format'][] = '%d';
 626              } else if ( $args['invite_sent'] == 'sent' ) {
 627                  $where_clauses['data']['invite_sent'] = 1;
 628                  $where_clauses['format'][] = '%d';
 629              }
 630          }
 631  
 632          // accepted.
 633          if ( ! empty( $args['accepted'] ) && 'all' !== $args['accepted'] ) {
 634              if ( $args['accepted'] == 'pending' ) {
 635                  $where_clauses['data']['accepted'] = 0;
 636                  $where_clauses['format'][] = '%d';
 637              } else if ( $args['accepted'] == 'accepted' ) {
 638                  $where_clauses['data']['accepted'] = 1;
 639                  $where_clauses['format'][] = '%d';
 640              }
 641          }
 642  
 643          // date_modified
 644          if ( ! empty( $args['date_modified'] ) ) {
 645              $where_clauses['data']['date_modified'] = $args['date_modified'];
 646              $where_clauses['format'][] = '%s';
 647          }
 648  
 649          return $where_clauses;
 650      }
 651  
 652      /** Public Static Methods *********************************************/
 653  
 654      /**
 655       * Get invitations, based on provided filter parameters.
 656       *
 657       * @since 5.0.0
 658       *
 659       * @param array $args {
 660       *     Associative array of arguments. All arguments but $page and
 661       *     $per_page can be treated as filter values for get_where_sql()
 662       *     and get_query_clauses(). All items are optional.
 663       *     @type int|array    $id                ID of invitation being updated.
 664       *                                           Can be an array of IDs.
 665       *     @type int|array    $user_id           ID of user being queried. Can be an
 666       *                                           Can be an array of IDs.
 667       *     @type int|array    $inviter_id        ID of user who created the
 668       *                                           invitation. Can be an array of IDs.
 669       *     @type string|array $invitee_email     Email address of invited users
 670       *                                             being queried. Can be an array of
 671       *                                           addresses.
 672       *     @type string|array $class             Name of the class to filter by.
 673       *                                           Can be an array of class names.
 674       *     @type int|array    $item_id           ID of associated item.
 675       *                                           Can be an array of multiple item IDs.
 676       *     @type int|array    $secondary_item_id ID of secondary associated item.
 677       *                                           Can be an array of multiple IDs.
 678       *     @type string|array $type              Type of item. An "invite" is sent
 679       *                                           from one user to another.
 680       *                                           A "request" is submitted by a
 681       *                                           user and no inviter is required.
 682       *                                           'all' returns all. Default: 'all'.
 683       *     @type string       $invite_sent       Limit to draft, sent or all
 684       *                                           'draft' limits to unsent invites,
 685       *                                           'sent' returns only sent invites,
 686       *                                           'all' returns all. Default: 'all'.
 687       *     @type bool         $accepted          Limit to accepted or
 688       *                                           not-yet-accepted invitations.
 689       *                                           'accepted' returns accepted invites,
 690       *                                           'pending' returns pending invites,
 691       *                                           'all' returns all. Default: 'pending'
 692       *     @type string       $search_terms      Term to match against class field.
 693       *     @type string       $order_by          Database column to order by.
 694       *     @type string       $sort_order        Either 'ASC' or 'DESC'.
 695       *     @type string       $order_by          Field to order results by.
 696       *     @type string       $sort_order        ASC or DESC.
 697       *     @type int          $page              Number of the current page of results.
 698       *                                           Default: false (no pagination,
 699       *                                           all items).
 700       *     @type int          $per_page          Number of items to show per page.
 701       *                                           Default: false (no pagination,
 702       *                                           all items).
 703       *     @type string       $fields            Which fields to return. Specify 'item_ids' to fetch a list of Item_IDs.
 704       *                                           Specify 'ids' to fetch a list of Invitation IDs.
 705       *                                           Default: 'all' (return BP_Invitation objects).
 706       * }
 707       *
 708       * @return array BP_Invitation objects | IDs of found invite.
 709       */
 710  	public static function get( $args = array() ) {
 711          global $wpdb;
 712          $invites_table_name = BP_Invitation_Manager::get_table_name();
 713  
 714          // Parse the arguments.
 715          $r  = bp_parse_args( $args, array(
 716              'id'                => false,
 717              'user_id'           => false,
 718              'inviter_id'        => false,
 719              'invitee_email'     => false,
 720              'class'             => false,
 721              'item_id'           => false,
 722              'secondary_item_id' => false,
 723              'type'              => 'all',
 724              'invite_sent'       => 'all',
 725              'accepted'          => 'pending',
 726              'search_terms'      => '',
 727              'order_by'          => false,
 728              'sort_order'        => false,
 729              'page'              => false,
 730              'per_page'          => false,
 731              'fields'            => 'all',
 732          ), 'bp_invitations_invitation_get' );
 733  
 734          $sql = array(
 735              'select'     => "SELECT",
 736              'fields'     => '',
 737              'from'       => "FROM {$invites_table_name} i",
 738              'where'      => '',
 739              'orderby'    => '',
 740              'pagination' => '',
 741          );
 742  
 743          if ( 'item_ids' === $r['fields'] ) {
 744              $sql['fields'] = "DISTINCT i.item_id";
 745          } else if ( 'user_ids' === $r['fields'] ) {
 746              $sql['fields'] = "DISTINCT i.user_id";
 747          } else if ( 'inviter_ids' === $r['fields'] ) {
 748              $sql['fields'] = "DISTINCT i.inviter_id";
 749          } else {
 750              $sql['fields'] = 'DISTINCT i.id';
 751          }
 752  
 753          // WHERE.
 754          $sql['where'] = self::get_where_sql( array(
 755              'id'                => $r['id'],
 756              'user_id'           => $r['user_id'],
 757              'inviter_id'        => $r['inviter_id'],
 758              'invitee_email'     => $r['invitee_email'],
 759              'class'             => $r['class'],
 760              'item_id'           => $r['item_id'],
 761              'secondary_item_id' => $r['secondary_item_id'],
 762              'type'              => $r['type'],
 763              'invite_sent'       => $r['invite_sent'],
 764              'accepted'          => $r['accepted'],
 765              'search_terms'      => $r['search_terms'],
 766          ) );
 767  
 768          // ORDER BY.
 769          $sql['orderby'] = self::get_order_by_sql( array(
 770              'order_by'   => $r['order_by'],
 771              'sort_order' => $r['sort_order']
 772          ) );
 773  
 774          // LIMIT %d, %d.
 775          $sql['pagination'] = self::get_paged_sql( array(
 776              'page'     => $r['page'],
 777              'per_page' => $r['per_page'],
 778          ) );
 779  
 780          $paged_invites_sql = "{$sql['select']} {$sql['fields']} {$sql['from']} {$sql['where']} {$sql['orderby']} {$sql['pagination']}";
 781  
 782          /**
 783           * Filters the pagination SQL statement.
 784           *
 785           * @since 5.0.0
 786           *
 787           * @param string $value Concatenated SQL statement.
 788           * @param array  $sql   Array of SQL parts before concatenation.
 789           * @param array  $r     Array of parsed arguments for the get method.
 790           */
 791          $paged_invites_sql = apply_filters( 'bp_invitations_get_paged_invitations_sql', $paged_invites_sql, $sql, $r );
 792  
 793          $cached = bp_core_get_incremented_cache( $paged_invites_sql, 'bp_invitations' );
 794          if ( false === $cached ) {
 795              $paged_invite_ids = $wpdb->get_col( $paged_invites_sql );
 796              bp_core_set_incremented_cache( $paged_invites_sql, 'bp_invitations', $paged_invite_ids );
 797          } else {
 798              $paged_invite_ids = $cached;
 799          }
 800  
 801          // Special return format cases.
 802          if ( in_array( $r['fields'], array( 'ids', 'item_ids', 'user_ids', 'inviter_ids' ), true ) ) {
 803              // We only want the field that was found.
 804              return array_map( 'intval', $paged_invite_ids );
 805          }
 806  
 807          $uncached_ids = bp_get_non_cached_ids( $paged_invite_ids, 'bp_invitations' );
 808          if ( $uncached_ids ) {
 809              $ids_sql = implode( ',', array_map( 'intval', $uncached_ids ) );
 810              $data_objects = $wpdb->get_results( "SELECT i.* FROM {$invites_table_name} i WHERE i.id IN ({$ids_sql})" );
 811              foreach ( $data_objects as $data_object ) {
 812                  wp_cache_set( $data_object->id, $data_object, 'bp_invitations' );
 813              }
 814          }
 815  
 816          $paged_invites = array();
 817          foreach ( $paged_invite_ids as $paged_invite_id ) {
 818              $paged_invites[] = new BP_Invitation( $paged_invite_id );
 819          }
 820  
 821          return $paged_invites;
 822      }
 823  
 824      /**
 825       * Get a count of total invitations matching a set of arguments.
 826       *
 827       * @since 5.0.0
 828       *
 829       * @see BP_Invitation::get() for a description of
 830       *      arguments.
 831       *
 832       * @param array $args See {@link BP_Invitation::get()}.
 833       * @return int Count of located items.
 834       */
 835  	public static function get_total_count( $args ) {
 836          global $wpdb;
 837          $invites_table_name = BP_Invitation_Manager::get_table_name();
 838  
 839          $r  = bp_parse_args( $args, array(
 840              'id'                => false,
 841              'user_id'           => false,
 842              'inviter_id'        => false,
 843              'invitee_email'     => false,
 844              'class'             => false,
 845              'item_id'           => false,
 846              'secondary_item_id' => false,
 847              'type'              => 'all',
 848              'invite_sent'       => 'all',
 849              'accepted'          => 'pending',
 850              'search_terms'      => '',
 851              'order_by'          => false,
 852              'sort_order'        => false,
 853              'page'              => false,
 854              'per_page'          => false,
 855              'fields'            => 'all',
 856          ), 'bp_invitations_invitation_get_total_count' );
 857  
 858          // Build the query
 859          $select_sql = "SELECT COUNT(*)";
 860          $from_sql   = "FROM {$invites_table_name}";
 861          $where_sql  = self::get_where_sql( $r );
 862          $sql        = "{$select_sql} {$from_sql} {$where_sql}";
 863  
 864          // Return the queried results
 865          return $wpdb->get_var( $sql );
 866      }
 867  
 868      /**
 869       * Update invitations.
 870       *
 871       * @since 5.0.0
 872       *
 873       * @see BP_Invitation::get() for a description of
 874       *      accepted update/where arguments.
 875       *
 876       * @param array $update_args Associative array of fields to update,
 877       *                           and the values to update them to. Of the format
 878       *                           array( 'user_id' => 4, 'class' => 'BP_Groups_Invitation_Manager', ).
 879       * @param array $where_args  Associative array of columns/values, to
 880       *                           determine which rows should be updated. Of the format
 881       *                           array( 'item_id' => 7, 'class' => 'BP_Groups_Invitation_Manager', ).
 882       * @return int|bool Number of rows updated on success, false on failure.
 883       */
 884  	public static function update( $update_args = array(), $where_args = array() ) {
 885          $update = self::get_query_clauses( $update_args );
 886          $where  = self::get_query_clauses( $where_args  );
 887  
 888          /**
 889           * Fires before an invitation is updated.
 890           *
 891           * @since 5.0.0
 892           *
 893           * @param array $where_args  Associative array of columns/values describing
 894           *                           invitations about to be deleted.
 895           * @param array $update_args Array of new values.
 896           */
 897          do_action( 'bp_invitation_before_update', $where_args, $update_args );
 898  
 899          $retval = self::_update( $update['data'], $where['data'], $update['format'], $where['format'] );
 900  
 901          // Clear matching items from the cache.
 902          $cache_args = $where_args;
 903          $cache_args['fields'] = 'ids';
 904          $maybe_cached_ids = self::get( $cache_args );
 905          foreach ( $maybe_cached_ids as $invite_id ) {
 906              wp_cache_delete( $invite_id, 'bp_invitations' );
 907          }
 908  
 909          /**
 910           * Fires after an invitation is updated.
 911           *
 912           * @since 5.0.0
 913           *
 914           * @param array $where_args  Associative array of columns/values describing
 915           *                           invitations about to be deleted.
 916           * @param array $update_args Array of new values.
 917           */
 918          do_action( 'bp_invitation_after_update', $where_args, $update_args );
 919  
 920          return $retval;
 921      }
 922  
 923      /**
 924       * Delete invitations.
 925       *
 926       * @since 5.0.0
 927       *
 928       * @see BP_Invitation::get() for a description of
 929       *      accepted where arguments.
 930       *
 931       * @param array $args Associative array of columns/values, to determine
 932       *                    which rows should be deleted.  Of the format
 933       *                    array( 'item_id' => 7, 'class' => 'BP_Groups_Invitation_Manager', ).
 934       * @return int|bool Number of rows deleted on success, false on failure.
 935       */
 936  	public static function delete( $args = array() ) {
 937          $where = self::get_query_clauses( $args );
 938  
 939          /**
 940           * Fires before an invitation is deleted.
 941           *
 942           * @since 5.0.0
 943           *
 944           * @param array $args Characteristics of the invitations to be deleted.
 945           */
 946          do_action( 'bp_invitation_before_delete', $args );
 947  
 948          // Clear matching items from the cache.
 949          $cache_args = $args;
 950          $cache_args['fields'] = 'ids';
 951          $maybe_cached_ids = self::get( $cache_args );
 952          foreach ( $maybe_cached_ids as $invite_id ) {
 953              wp_cache_delete( $invite_id, 'bp_invitations' );
 954          }
 955  
 956          $retval = self::_delete( $where['data'], $where['format'] );
 957  
 958          /**
 959           * Fires after an invitation is deleted.
 960           *
 961           * @since 5.0.0
 962           *
 963           * @param array $args Characteristics of the invitations just deleted.
 964           */
 965          do_action( 'bp_invitation_after_delete', $args );
 966  
 967          return $retval;
 968      }
 969  
 970      /** Convenience methods ***********************************************/
 971  
 972      /**
 973       * Delete a single invitation by ID.
 974       *
 975       * @since 5.0.0
 976       *
 977       * @see BP_Invitation::delete() for explanation of
 978       *      return value.
 979       *
 980       * @param int $id ID of the invitation item to be deleted.
 981       * @return bool True on success, false on failure.
 982       */
 983  	public static function delete_by_id( $id ) {
 984          return self::delete( array(
 985              'id' => $id,
 986          ) );
 987      }
 988  
 989      /** Sent status ***********************************************************/
 990  
 991      /**
 992       * Mark specific invitations as sent by invitation ID.
 993       *
 994       * @since 5.0.0
 995       *
 996       * @param int   $id   The ID of the invitation to mark as sent.
 997       * @param array $args {
 998       *     Optional. Invitation characteristics used
 999       *     to override certain sending behaviors.
1000       *
1001       *     @type string $date_modified Modified time in 'Y-m-d h:i:s' format, GMT.
1002       *                                 Defaults to current time if not specified.
1003       * }
1004       * @return int|bool The number of rows updated, or false on error.
1005       */
1006  	public static function mark_sent( $id = 0, $args = array() ) {
1007  
1008          if ( ! $id ) {
1009              return false;
1010          }
1011  
1012          // Values to be updated.
1013          $update_args = array(
1014              'invite_sent'   => 'sent',
1015              'date_modified' => bp_core_current_time(),
1016          );
1017          // Respect a specified `date-modified`.
1018          if ( ! empty( $args['date_modified'] ) ) {
1019              $update_args['date_modified'] = $args['date_modified'];
1020          }
1021  
1022          // WHERE clauses.
1023          $where_args = array(
1024              'id' => $id,
1025          );
1026  
1027          return self::update( $update_args, $where_args );
1028      }
1029  
1030      /**
1031       * Mark invitations as sent that are found by user_id, inviter_id, item id, and optional
1032       * secondary item id, and class name.
1033       *
1034       * @since 5.0.0
1035       *
1036       * @param array $args See BP_Invitation::update().
1037       * @return int|bool The number of rows updated, or false on error.
1038       */
1039  	public static function mark_sent_by_data( $args ) {
1040  
1041          // Values to be updated.
1042          $update_args = array(
1043              'invite_sent'   => 'sent',
1044              'date_modified' => bp_core_current_time(),
1045          );
1046          // Respect a specified `date-modified`.
1047          if ( ! empty( $args['date_modified'] ) ) {
1048              $update_args['date_modified'] = $args['date_modified'];
1049          }
1050  
1051          return self::update( $update_args, $args );
1052      }
1053  
1054      /** Accepted status ***********************************************************/
1055  
1056      /**
1057       * Mark specific invitations as accepted by invitation ID.
1058       *
1059       * @since 5.0.0
1060       *
1061       * @param int   $id   The ID of the invitation to mark as sent.
1062       * @param array $args {
1063       *     Optional. Invitation characteristics used
1064       *     to override certain sending behaviors.
1065       *
1066       *     @type string $date_modified Modified time in 'Y-m-d h:i:s' format, GMT.
1067       *                                 Defaults to current time if not specified.
1068       * }
1069       * @return int|bool The number of rows updated, or false on error.
1070       */
1071  	public static function mark_accepted( $id = 0, $args = array() ) {
1072  
1073          if ( ! $id ) {
1074              return false;
1075          }
1076  
1077          // Values to be updated.
1078          $update_args = array(
1079              'accepted'      => 'accepted',
1080              'date_modified' => bp_core_current_time(),
1081          );
1082          // Respect a specified `date-modified`.
1083          if ( ! empty( $args['date_modified'] ) ) {
1084              $update_args['date_modified'] = $args['date_modified'];
1085          }
1086  
1087          // WHERE clauses.
1088          $where_args = array(
1089              'id' => $id,
1090          );
1091  
1092          return self::update( $update_args, $where_args );
1093      }
1094  
1095      /**
1096       * Mark invitations as accepted that are found by user_id, inviter_id,
1097       * item id, and optional secondary item id, and class name.
1098       *
1099       * @since 5.0.0
1100       *
1101       * @param array $args See BP_Invitation::update().
1102       * @return int|bool The number of rows updated, or false on error.
1103       */
1104  	public static function mark_accepted_by_data( $args ) {
1105  
1106          // Values to be updated.
1107          $update_args = array(
1108              'accepted'      => 'accepted',
1109              'date_modified' => bp_core_current_time(),
1110          );
1111          // Respect a specified `date-modified`.
1112          if ( ! empty( $args['date_modified'] ) ) {
1113              $update_args['date_modified'] = $args['date_modified'];
1114          }
1115  
1116          return self::update( $update_args, $args );
1117      }
1118  
1119  }


Generated: Sun Apr 18 01:01:43 2021 Cross-referenced by PHPXref 0.7.1