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


Generated: Wed Oct 9 01:00:59 2024 Cross-referenced by PHPXref 0.7.1