[ Index ]

PHP Cross Reference of BuddyPress

title

Body

[close]

/src/bp-notifications/ -> bp-notifications-functions.php (source)

   1  <?php
   2  /**
   3   * BuddyPress Member Notifications Functions.
   4   *
   5   * Functions and filters used in the Notifications component.
   6   *
   7   * @package BuddyPress
   8   * @subpackage NotificationsFunctions
   9   * @since 1.9.0
  10   */
  11  
  12  // Exit if accessed directly.
  13  defined( 'ABSPATH' ) || exit;
  14  
  15  /**
  16   * Add a notification for a specific user, from a specific component.
  17   *
  18   * @since 1.9.0
  19   *
  20   * @param array $args {
  21   *     Array of arguments describing the notification. All are optional.
  22   *     @type int    $user_id           ID of the user to associate the notification with.
  23   *     @type int    $item_id           ID of the item to associate the notification with.
  24   *     @type int    $secondary_item_id ID of the secondary item to associate the
  25   *                                     notification with.
  26   *     @type string $component_name    Name of the component to associate the
  27   *                                     notification with.
  28   *     @type string $component_action  Name of the action to associate the
  29   *                                     notification with.
  30   *     @type string $date_notified     Timestamp for the notification.
  31   * }
  32   * @return int|bool ID of the newly created notification on success, false on failure.
  33   */
  34  function bp_notifications_add_notification( $args = array() ) {
  35  
  36      $r = bp_parse_args(
  37          $args,
  38          array(
  39              'user_id'           => 0,
  40              'item_id'           => 0,
  41              'secondary_item_id' => 0,
  42              'component_name'    => '',
  43              'component_action'  => '',
  44              'date_notified'     => bp_core_current_time(),
  45              'is_new'            => 1,
  46              'allow_duplicate'   => false,
  47          ),
  48          'notifications_add_notification'
  49      );
  50  
  51      // Check for existing duplicate notifications.
  52      if ( ! $r['allow_duplicate'] ) {
  53          // Date_notified, allow_duplicate don't count toward
  54          // duplicate status.
  55          $existing = BP_Notifications_Notification::get( array(
  56              'user_id'           => $r['user_id'],
  57              'item_id'           => $r['item_id'],
  58              'secondary_item_id' => $r['secondary_item_id'],
  59              'component_name'    => $r['component_name'],
  60              'component_action'  => $r['component_action'],
  61              'is_new'            => $r['is_new'],
  62          ) );
  63  
  64          if ( ! empty( $existing ) ) {
  65              return false;
  66          }
  67      }
  68  
  69      // Setup the new notification.
  70      $notification                    = new BP_Notifications_Notification;
  71      $notification->user_id           = $r['user_id'];
  72      $notification->item_id           = $r['item_id'];
  73      $notification->secondary_item_id = $r['secondary_item_id'];
  74      $notification->component_name    = $r['component_name'];
  75      $notification->component_action  = $r['component_action'];
  76      $notification->date_notified     = $r['date_notified'];
  77      $notification->is_new            = $r['is_new'];
  78  
  79      // Save the new notification.
  80      return $notification->save();
  81  }
  82  
  83  /**
  84   * Get a specific notification by its ID.
  85   *
  86   * @since 1.9.0
  87   *
  88   * @param int $id ID of the notification.
  89   * @return BP_Notifications_Notification Notification object for ID specified.
  90   */
  91  function bp_notifications_get_notification( $id ) {
  92      return new BP_Notifications_Notification( $id );
  93  }
  94  
  95  /**
  96   * Delete a specific notification by its ID.
  97   *
  98   * @since 1.9.0
  99   *
 100   * @param int $id ID of the notification to delete.
 101   * @return false|int Integer on success, false on failure.
 102   */
 103  function bp_notifications_delete_notification( $id ) {
 104      if ( ! bp_notifications_check_notification_access( bp_displayed_user_id(), $id ) ) {
 105          return false;
 106      }
 107  
 108      return BP_Notifications_Notification::delete( array( 'id' => $id ) );
 109  }
 110  
 111  /**
 112   * Mark notification read/unread for a user by ID.
 113   *
 114   * Used when clearing out notifications for a specific notification item.
 115   *
 116   * @since 1.9.0
 117   *
 118   * @param int      $id     ID of the notification.
 119   * @param int|bool $is_new 0 for read, 1 for unread.
 120   * @return false|int Number of rows updated on success, false on failure.
 121   */
 122  function bp_notifications_mark_notification( $id, $is_new = false ) {
 123      if ( ! bp_notifications_check_notification_access( bp_displayed_user_id(), $id ) ) {
 124          return false;
 125      }
 126  
 127      return BP_Notifications_Notification::update(
 128          array( 'is_new' => $is_new ),
 129          array( 'id'     => $id     )
 130      );
 131  }
 132  
 133  /**
 134   * Get all notifications for a user and cache them.
 135   *
 136   * @since 2.1.0
 137   *
 138   * @param int $user_id ID of the user whose notifications are being fetched.
 139   * @return array $notifications Array of notifications for user.
 140   */
 141  function bp_notifications_get_all_notifications_for_user( $user_id = 0 ) {
 142  
 143      // Default to displayed user if no ID is passed.
 144      if ( empty( $user_id ) ) {
 145          $user_id = ( bp_displayed_user_id() ) ? bp_displayed_user_id() : bp_loggedin_user_id();
 146      }
 147  
 148      // Get notifications out of the cache, or query if necessary.
 149      $notifications = wp_cache_get( 'all_for_user_' . $user_id, 'bp_notifications' );
 150      if ( false === $notifications ) {
 151          $notifications = BP_Notifications_Notification::get( array(
 152              'user_id' => $user_id,
 153          ) );
 154          wp_cache_set( 'all_for_user_' . $user_id, $notifications, 'bp_notifications' );
 155      }
 156  
 157      /**
 158       * Filters all notifications for a user.
 159       *
 160       * @since 2.1.0
 161       *
 162       * @param array $notifications Array of notifications for user.
 163       * @param int   $user_id       ID of the user being fetched.
 164       */
 165      return apply_filters( 'bp_notifications_get_all_notifications_for_user', $notifications, $user_id );
 166  }
 167  
 168  /**
 169   * Get a user's unread notifications, grouped by component and action.
 170   *
 171   * This function returns a list of notifications collapsed by component + action.
 172   * See BP_Notifications_Notification::get_grouped_notifications_for_user() for
 173   * more details.
 174   *
 175   * @since 3.0.0
 176   *
 177   * @param int $user_id ID of the user whose notifications are being fetched.
 178   * @return array $notifications
 179   */
 180  function bp_notifications_get_grouped_notifications_for_user( $user_id = 0 ) {
 181      if ( empty( $user_id ) ) {
 182          $user_id = ( bp_displayed_user_id() ) ? bp_displayed_user_id() : bp_loggedin_user_id();
 183      }
 184  
 185      $notifications = wp_cache_get( $user_id, 'bp_notifications_grouped_notifications' );
 186      if ( false === $notifications ) {
 187          $notifications = BP_Notifications_Notification::get_grouped_notifications_for_user( $user_id );
 188          wp_cache_set( $user_id, $notifications, 'bp_notifications_grouped_notifications' );
 189      }
 190  
 191      return $notifications;
 192  }
 193  
 194  /**
 195   * Get notifications for a specific user.
 196   *
 197   * @since 1.9.0
 198   *
 199   * @param int    $user_id ID of the user whose notifications are being fetched.
 200   * @param string $format  Format of the returned values. 'string' returns HTML,
 201   *                        while 'object' returns a structured object for parsing.
 202   * @return mixed Object or array on success, false on failure.
 203   */
 204  function bp_notifications_get_notifications_for_user( $user_id, $format = 'string' ) {
 205      $bp = buddypress();
 206  
 207      $notifications = bp_notifications_get_grouped_notifications_for_user( $user_id );
 208  
 209      // Calculate a renderable output for each notification type.
 210      foreach ( $notifications as $notification_item ) {
 211  
 212          $component_name = $notification_item->component_name;
 213          // We prefer that extended profile component-related notifications use
 214          // the component_name of 'xprofile'. However, the extended profile child
 215          // object in the $bp object is keyed as 'profile', which is where we need
 216          // to look for the registered notification callback.
 217          if ( 'xprofile' == $notification_item->component_name ) {
 218              $component_name = 'profile';
 219          }
 220  
 221          // Callback function exists.
 222          if ( isset( $bp->{$component_name}->notification_callback ) && is_callable( $bp->{$component_name}->notification_callback ) ) {
 223  
 224              // Function should return an object.
 225              if ( 'object' === $format ) {
 226  
 227                  // Retrieve the content of the notification using the callback.
 228                  $content = call_user_func( $bp->{$component_name}->notification_callback, $notification_item->component_action, $notification_item->item_id, $notification_item->secondary_item_id, $notification_item->total_count, 'array', $notification_item->id );
 229  
 230                  // Create the object to be returned.
 231                  $notification_object = $notification_item;
 232  
 233                  // Minimal backpat with non-compatible notification
 234                  // callback functions.
 235                  if ( is_string( $content ) ) {
 236                      $notification_object->content = $content;
 237                      $notification_object->href    = bp_loggedin_user_domain();
 238                  } else {
 239                      $notification_object->content = isset( $content['text'] ) ? $content['text'] : '';
 240                      $notification_object->href    = isset( $content['link'] ) ? $content['link'] : '';
 241                  }
 242  
 243                  $renderable[] = $notification_object;
 244  
 245                  // Return an array of content strings.
 246              } else {
 247                  $content      = call_user_func( $bp->{$component_name}->notification_callback, $notification_item->component_action, $notification_item->item_id, $notification_item->secondary_item_id, $notification_item->total_count, 'string', $notification_item->id );
 248                  $renderable[] = $content;
 249              }
 250  
 251              // @deprecated format_notification_function - 1.5
 252          } elseif ( isset( $bp->{$component_name}->format_notification_function ) && function_exists( $bp->{$component_name}->format_notification_function ) ) {
 253              $renderable[] = call_user_func( $bp->{$component_name}->notification_callback, $notification_item->component_action, $notification_item->item_id, $notification_item->secondary_item_id, $notification_item->total_count );
 254  
 255              // Allow non BuddyPress components to hook in.
 256          } else {
 257  
 258              // The array to reference with apply_filters_ref_array().
 259              $ref_array = array(
 260                  $notification_item->component_action,
 261                  $notification_item->item_id,
 262                  $notification_item->secondary_item_id,
 263                  $notification_item->total_count,
 264                  $format,
 265                  $notification_item->component_action, // Duplicated so plugins can check the canonical action name.
 266                  $component_name,
 267                  $notification_item->id,
 268              );
 269  
 270              // Function should return an object.
 271              if ( 'object' === $format ) {
 272  
 273                  /**
 274                   * Filters the notification content for notifications created by plugins.
 275                   * If your plugin extends the {@link BP_Component} class, you should use the
 276                   * 'notification_callback' parameter in your extended
 277                   * {@link BP_Component::setup_globals()} method instead.
 278                   *
 279                   * @since 1.9.0
 280                   * @since 2.6.0 Added $component_action_name, $component_name, $id as parameters.
 281                   *
 282                   * @param string $content               Component action. Deprecated. Do not do checks against this! Use
 283                   *                                      the 6th parameter instead - $component_action_name.
 284                   * @param int    $item_id               Notification item ID.
 285                   * @param int    $secondary_item_id     Notification secondary item ID.
 286                   * @param int    $action_item_count     Number of notifications with the same action.
 287                   * @param string $format                Format of return. Either 'string' or 'object'.
 288                   * @param string $component_action_name Canonical notification action.
 289                   * @param string $component_name        Notification component ID.
 290                   * @param int    $id                    Notification ID.
 291                   *
 292                   * @return string|array If $format is 'string', return a string of the notification content.
 293                   *                      If $format is 'object', return an array formatted like:
 294                   *                      array( 'text' => 'CONTENT', 'link' => 'LINK' )
 295                   */
 296                  $content = apply_filters_ref_array( 'bp_notifications_get_notifications_for_user', $ref_array );
 297  
 298                  // Create the object to be returned.
 299                  $notification_object = $notification_item;
 300  
 301                  // Minimal backpat with non-compatible notification
 302                  // callback functions.
 303                  if ( is_string( $content ) ) {
 304                      $notification_object->content = $content;
 305                      $notification_object->href    = bp_loggedin_user_domain();
 306                  } else {
 307                      $notification_object->content = $content['text'];
 308                      $notification_object->href    = $content['link'];
 309                  }
 310  
 311                  $renderable[] = $notification_object;
 312  
 313                  // Return an array of content strings.
 314              } else {
 315  
 316                  /** This filters is documented in bp-notifications/bp-notifications-functions.php */
 317                  $renderable[] = apply_filters_ref_array( 'bp_notifications_get_notifications_for_user', $ref_array );
 318              }
 319          }
 320      }
 321  
 322      // If renderable is empty array, set to false.
 323      if ( empty( $renderable ) ) {
 324          $renderable = false;
 325      }
 326  
 327      /**
 328       * Filters the final array of notifications to be displayed for a user.
 329       *
 330       * @since 1.6.0
 331       *
 332       * @param array|bool $renderable Array of notifications to render or false if no notifications.
 333       * @param int        $user_id    ID of the user whose notifications are being displayed.
 334       * @param string     $format     Display format requested for the notifications.
 335       */
 336      return apply_filters( 'bp_core_get_notifications_for_user', $renderable, $user_id, $format );
 337  }
 338  
 339  /** Delete ********************************************************************/
 340  
 341  /**
 342   * Delete notifications for a user by type.
 343   *
 344   * Used when clearing out notifications for a specific component when the user
 345   * has visited that component.
 346   *
 347   * @since 1.9.0
 348   *
 349   * @param int    $user_id          ID of the user whose notifications are being deleted.
 350   * @param string $component_name   Name of the associated component.
 351   * @param string $component_action Name of the associated action.
 352   * @return int|false True on success, false on failure.
 353   */
 354  function bp_notifications_delete_notifications_by_type( $user_id, $component_name, $component_action ) {
 355      return BP_Notifications_Notification::delete( array(
 356          'user_id'          => $user_id,
 357          'component_name'   => $component_name,
 358          'component_action' => $component_action,
 359      ) );
 360  }
 361  
 362  /**
 363   * Delete notifications for an item ID.
 364   *
 365   * Used when clearing out notifications for a specific component when the user
 366   * has visited that component.
 367   *
 368   * @since 1.9.0
 369   *
 370   * @param int      $user_id           ID of the user whose notifications are being deleted.
 371   * @param int      $item_id           ID of the associated item.
 372   * @param string   $component_name    Name of the associated component.
 373   * @param string   $component_action  Name of the associated action.
 374   * @param int|bool $secondary_item_id ID of the secondary associated item.
 375   * @return int|false True on success, false on failure.
 376   */
 377  function bp_notifications_delete_notifications_by_item_id( $user_id, $item_id, $component_name, $component_action, $secondary_item_id = false ) {
 378      return BP_Notifications_Notification::delete( array(
 379          'user_id'           => $user_id,
 380          'item_id'           => $item_id,
 381          'secondary_item_id' => $secondary_item_id,
 382          'component_name'    => $component_name,
 383          'component_action'  => $component_action,
 384      ) );
 385  }
 386  
 387  /**
 388   * Delete notifications by notification ids.
 389   *
 390   * @since 10.0.0
 391   *
 392   * @param  int[]     $ids IDs of the associated notifications.
 393   * @return int|false      The number of rows updated. False on error.
 394   */
 395  function bp_notifications_delete_notifications_by_ids( $ids ) {
 396      return BP_Notifications_Notification::delete_by_id_list( 'id', $ids );
 397  }
 398  
 399  /**
 400   * Delete notifications by item ids and user.
 401   *
 402   * @since 10.0.0
 403   *
 404   * @param  int       $user_id          ID of the user whose notifications are being deleted.
 405   * @param  int[]     $item_ids         IDs of the associated items.
 406   * @param  string    $component_name   Name of the associated component.
 407   * @param  string    $component_action Name of the associated action.
 408   * @return int|false                   The number of rows updated. False on error.
 409   */
 410  function bp_notifications_delete_notifications_by_item_ids( $user_id, $item_ids, $component_name, $component_action ) {
 411      return BP_Notifications_Notification::delete_by_id_list(
 412          'item_id',
 413          $item_ids,
 414          array(
 415              'user_id'          => $user_id,
 416              'component_name'   => $component_name,
 417              'component_action' => $component_action
 418          )
 419      );
 420  }
 421  
 422  /**
 423   * Delete all notifications by type.
 424   *
 425   * Used when clearing out notifications for an entire component.
 426   *
 427   * @since 1.9.0
 428   *
 429   * @param int         $item_id           ID of the user whose notifications are being deleted.
 430   * @param string      $component_name    Name of the associated component.
 431   * @param string|bool $component_action  Optional. Name of the associated action.
 432   * @param int|bool    $secondary_item_id Optional. ID of the secondary associated item.
 433   * @return int|false True on success, false on failure.
 434   */
 435  function bp_notifications_delete_all_notifications_by_type( $item_id, $component_name, $component_action = false, $secondary_item_id = false ) {
 436      return BP_Notifications_Notification::delete( array(
 437          'item_id'           => $item_id,
 438          'secondary_item_id' => $secondary_item_id,
 439          'component_name'    => $component_name,
 440          'component_action'  => $component_action,
 441      ) );
 442  }
 443  
 444  /**
 445   * Delete all notifications from a user.
 446   *
 447   * Used when clearing out all notifications for a user, when deleted or spammed.
 448   *
 449   * @todo This function assumes that items with the user_id in the item_id slot
 450   *       are associated with that user. However, this will only be true with
 451   *       certain components (such as Friends). Use with caution!
 452   *
 453   * @since 1.9.0
 454   *
 455   * @param int    $user_id          ID of the user whose associated items are being deleted.
 456   * @param string $component_name   Name of the associated component.
 457   * @param string $component_action Name of the associated action.
 458   * @return int|false True on success, false on failure.
 459   */
 460  function bp_notifications_delete_notifications_from_user( $user_id, $component_name, $component_action ) {
 461      return BP_Notifications_Notification::delete( array(
 462          'item_id'           => $user_id,
 463          'component_name'    => $component_name,
 464          'component_action'  => $component_action,
 465      ) );
 466  }
 467  
 468  /**
 469   * Delete a user's notifications when the user is deleted.
 470   *
 471   * @since 2.5.0
 472   *
 473   * @param int $user_id ID of the user who is about to be deleted.
 474   * @return int|false The number of rows deleted, or false on error.
 475   */
 476  function bp_notifications_delete_notifications_on_user_delete( $user_id ) {
 477      return BP_Notifications_Notification::delete( array(
 478          'user_id'           => $user_id,
 479          'item_id'           => false,
 480          'secondary_item_id' => false,
 481          'component_action'  => false,
 482          'component_name'    => false,
 483      ) );
 484  }
 485  add_action( 'wpmu_delete_user', 'bp_notifications_delete_notifications_on_user_delete' );
 486  
 487  /**
 488   * Deletes user notifications data on the 'delete_user' hook.
 489   *
 490   * @since 6.0.0
 491   *
 492   * @param int $user_id The ID of the deleted user.
 493   */
 494  function bp_notifications_delete_notifications_on_delete_user( $user_id ) {
 495      if ( ! bp_remove_user_data_on_delete_user_hook( 'notifications', $user_id ) ) {
 496          return;
 497      }
 498  
 499      bp_notifications_delete_notifications_on_user_delete( $user_id );
 500  }
 501  
 502  add_action( 'delete_user', 'bp_notifications_delete_notifications_on_delete_user' );
 503  
 504  /** Mark **********************************************************************/
 505  
 506  /**
 507   * Mark notifications read/unread for a user by type.
 508   *
 509   * Used when clearing out notifications for a specific component when the user
 510   * has visited that component.
 511   *
 512   * @since 1.9.0
 513   *
 514   * @param int      $user_id          ID of the user whose notifications are being deleted.
 515   * @param string   $component_name   Name of the associated component.
 516   * @param string   $component_action Name of the associated action.
 517   * @param int|bool $is_new           0 for read, 1 for unread.
 518   * @return int|false True on success, false on failure.
 519   */
 520  function bp_notifications_mark_notifications_by_type( $user_id, $component_name, $component_action, $is_new = false ) {
 521      return BP_Notifications_Notification::update(
 522          array(
 523              'is_new' => $is_new,
 524          ),
 525          array(
 526              'user_id'          => $user_id,
 527              'component_name'   => $component_name,
 528              'component_action' => $component_action,
 529          )
 530      );
 531  }
 532  
 533  /**
 534   * Mark notifications read/unread for an item ID.
 535   *
 536   * Used when clearing out notifications for a specific component when the user
 537   * has visited that component.
 538   *
 539   * @since 1.9.0
 540   *
 541   * @param int      $user_id           ID of the user whose notifications are being deleted.
 542   * @param int      $item_id           ID of the associated item.
 543   * @param string   $component_name    Name of the associated component.
 544   * @param string   $component_action  Name of the associated action.
 545   * @param int|bool $secondary_item_id ID of the secondary associated item.
 546   * @param int|bool $is_new            0 for read, 1 for unread.
 547   * @return int|false True on success, false on failure.
 548   */
 549  function bp_notifications_mark_notifications_by_item_id( $user_id, $item_id, $component_name, $component_action, $secondary_item_id = false, $is_new = false ) {
 550      return BP_Notifications_Notification::update(
 551          array(
 552              'is_new' => $is_new,
 553          ),
 554          array(
 555              'user_id'           => $user_id,
 556              'item_id'           => $item_id,
 557              'secondary_item_id' => $secondary_item_id,
 558              'component_name'    => $component_name,
 559              'component_action'  => $component_action,
 560          )
 561      );
 562  }
 563  
 564  /**
 565   * Mark all notifications read/unread by type.
 566   *
 567   * Used when clearing out notifications for an entire component.
 568   *
 569   * @since 1.9.0
 570   *
 571   * @param int         $item_id           ID of the user whose notifications are being deleted.
 572   * @param string      $component_name    Name of the associated component.
 573   * @param string|bool $component_action  Optional. Name of the associated action.
 574   * @param int|bool    $secondary_item_id Optional. ID of the secondary associated item.
 575   * @param int|bool    $is_new            0 for read, 1 for unread.
 576   * @return int|false True on success, false on failure.
 577   */
 578  function bp_notifications_mark_all_notifications_by_type( $item_id, $component_name, $component_action = false, $secondary_item_id = false, $is_new = false ) {
 579      return BP_Notifications_Notification::update(
 580          array(
 581              'is_new' => $is_new,
 582          ),
 583          array(
 584              'item_id'           => $item_id,
 585              'secondary_item_id' => $secondary_item_id,
 586              'component_name'    => $component_name,
 587              'component_action'  => $component_action,
 588          )
 589      );
 590  }
 591  
 592  /**
 593   * Mark all notifications read/unread from a user.
 594   *
 595   * Used when clearing out all notifications for a user, when deleted or spammed.
 596   *
 597   * @todo This function assumes that items with the user_id in the item_id slot
 598   *       are associated with that user. However, this will only be true with
 599   *       certain components (such as Friends). Use with caution!
 600   *
 601   * @since 1.9.0
 602   *
 603   * @param int      $user_id          ID of the user whose associated items are being deleted.
 604   * @param string   $component_name   Name of the associated component.
 605   * @param string   $component_action Name of the associated action.
 606   * @param int|bool $is_new           0 for read, 1 for unread.
 607   * @return int|false True on success, false on failure.
 608   */
 609  function bp_notifications_mark_notifications_from_user( $user_id, $component_name, $component_action, $is_new = false ) {
 610      return BP_Notifications_Notification::update(
 611          array(
 612              'is_new' => $is_new,
 613          ),
 614          array(
 615              'item_id'          => $user_id,
 616              'component_name'   => $component_name,
 617              'component_action' => $component_action,
 618          )
 619      );
 620  }
 621  
 622  /**
 623   * Mark notifications read/unread by item ids and user.
 624   *
 625   * @since 10.0.0
 626   *
 627   * @param  int       $user_id          ID of the user whose notifications are being deleted.
 628   * @param  int[]     $item_ids         IDs of the associated items.
 629   * @param  string    $component_name   Name of the associated component.
 630   * @param  string    $component_action Name of the associated action.
 631   * @param  int|false $is_new           0 for read, 1 for unread.
 632   * @return int|false                   The number of rows updated. False on error.
 633   */
 634  function bp_notifications_mark_notifications_by_item_ids( $user_id, $item_ids, $component_name, $component_action, $is_new = false ) {
 635      return BP_Notifications_Notification::update_id_list(
 636          'item_id',
 637          $item_ids,
 638          array(
 639              'is_new' => $is_new,
 640          ),
 641          array(
 642              'user_id'          => $user_id,
 643              'component_name'   => $component_name,
 644              'component_action' => $component_action
 645          )
 646      );
 647  }
 648  
 649  /**
 650   * Mark notifications read/unread by notification ids.
 651   *
 652   * @since 10.0.0
 653   *
 654   * @param  int[]     $ids     IDs of the associated notification items.
 655   * @param  int|false $is_new  0 for read, 1 for unread.
 656   * @return int|false          The number of rows updated. False on error.
 657   */
 658  function bp_notifications_mark_notifications_by_ids( $ids, $is_new = false ) {
 659      return BP_Notifications_Notification::update_id_list(
 660          'id',
 661          $ids,
 662          array(
 663              'is_new' => $is_new,
 664          )
 665      );
 666  }
 667  
 668  /** Helpers *******************************************************************/
 669  
 670  /**
 671   * Check if a user has access to a specific notification.
 672   *
 673   * Used before deleting a notification for a user.
 674   *
 675   * @since 1.9.0
 676   *
 677   * @param int $user_id         ID of the user being checked.
 678   * @param int $notification_id ID of the notification being checked.
 679   * @return bool True if the notification belongs to the user, otherwise false.
 680   */
 681  function bp_notifications_check_notification_access( $user_id, $notification_id ) {
 682      return (bool) BP_Notifications_Notification::check_access( $user_id, $notification_id );
 683  }
 684  
 685  /**
 686   * Get a count of unread notification items for a user.
 687   *
 688   * @since 1.9.0
 689   *
 690   * @param int $user_id ID of the user whose unread notifications are being
 691   *                     counted.
 692   * @return int Unread notification count.
 693   */
 694  function bp_notifications_get_unread_notification_count( $user_id = 0 ) {
 695      if ( empty( $user_id ) ) {
 696          $user_id = ( bp_displayed_user_id() ) ? bp_displayed_user_id() : bp_loggedin_user_id();
 697      }
 698  
 699      $count = wp_cache_get( $user_id, 'bp_notifications_unread_count' );
 700      if ( false === $count ) {
 701          $count = BP_Notifications_Notification::get_total_count( array(
 702              'user_id' => $user_id,
 703              'is_new'  => true,
 704          ) );
 705          wp_cache_set( $user_id, $count, 'bp_notifications_unread_count' );
 706      }
 707  
 708      /**
 709       * Filters the count of unread notification items for a user.
 710       *
 711       * @since 1.9.0
 712       * @since 2.7.0 Added user ID parameter.
 713       *
 714       * @param int $count   Count of unread notification items for a user.
 715       * @param int $user_id User ID for notifications count.
 716       */
 717      return apply_filters( 'bp_notifications_get_total_notification_count', (int) $count, $user_id );
 718  }
 719  
 720  /**
 721   * Return an array of component names that are currently active and have
 722   * registered Notifications callbacks.
 723   *
 724   * @since 1.9.1
 725   *
 726   * @see http://buddypress.trac.wordpress.org/ticket/5300
 727   *
 728   * @return array $component_names Array of registered components.
 729   */
 730  function bp_notifications_get_registered_components() {
 731  
 732      // Load BuddyPress.
 733      $bp = buddypress();
 734  
 735      // Setup return value.
 736      $component_names = array();
 737  
 738      // Get the active components.
 739      $active_components = array_keys( $bp->active_components );
 740  
 741      // Loop through components, look for callbacks, add to return value.
 742      foreach ( $active_components as $component ) {
 743          if ( !empty( $bp->$component->notification_callback ) ) {
 744              $component_names[] = $component;
 745          }
 746          // The extended profile component is identified in the active_components array as 'xprofile'.
 747          // However, the extended profile child object has the key 'profile' in the $bp object.
 748          if ( 'xprofile' == $component && ! empty( $bp->profile->notification_callback ) ) {
 749              $component_names[] = $component;
 750          }
 751      }
 752  
 753      /**
 754       * Filters active components with registered notifications callbacks.
 755       *
 756       * @since 1.9.1
 757       *
 758       * @param array $component_names   Array of registered component names.
 759       * @param array $active_components Array of active components.
 760       */
 761      return apply_filters( 'bp_notifications_get_registered_components', $component_names, $active_components );
 762  }
 763  
 764  /**
 765   * Catch and route the 'settings' notifications screen.
 766   *
 767   * This is currently unused.
 768   *
 769   * @since 1.9.0
 770   */
 771  function bp_notifications_screen_settings() {}
 772  
 773  /** Meta **********************************************************************/
 774  
 775  /**
 776   * Delete a meta entry from the DB for a notification item.
 777   *
 778   * @since 2.3.0
 779   *
 780   * @global object $wpdb WordPress database access object.
 781   *
 782   * @param int    $notification_id ID of the notification item whose metadata is being deleted.
 783   * @param string $meta_key        Optional. The key of the metadata being deleted. If
 784   *                                omitted, all metadata associated with the notification
 785   *                                item will be deleted.
 786   * @param string $meta_value      Optional. If present, the metadata will only be
 787   *                                deleted if the meta_value matches this parameter.
 788   * @param bool   $delete_all      Optional. If true, delete matching metadata entries
 789   *                                for all objects, ignoring the specified object_id. Otherwise,
 790   *                                only delete matching metadata entries for the specified
 791   *                                notification item. Default: false.
 792   * @return bool                   True on success, false on failure.
 793   */
 794  function bp_notifications_delete_meta( $notification_id, $meta_key = '', $meta_value = '', $delete_all = false ) {
 795  
 796      // Legacy - if no meta_key is passed, delete all for the item.
 797      if ( empty( $meta_key ) ) {
 798          $all_meta = bp_notifications_get_meta( $notification_id );
 799          $keys     = ! empty( $all_meta )
 800              ? array_keys( $all_meta )
 801              : array();
 802  
 803          // With no meta_key, ignore $delete_all.
 804          $delete_all = false;
 805      } else {
 806          $keys = array( $meta_key );
 807      }
 808  
 809      $retval = true;
 810  
 811      add_filter( 'query', 'bp_filter_metaid_column_name' );
 812      foreach ( $keys as $key ) {
 813          $retval = delete_metadata( 'notification', $notification_id, $key, $meta_value, $delete_all );
 814      }
 815      remove_filter( 'query', 'bp_filter_metaid_column_name' );
 816  
 817      return $retval;
 818  }
 819  
 820  /**
 821   * Get metadata for a given notification item.
 822   *
 823   * @since 2.3.0
 824   *
 825   * @param int    $notification_id ID of the notification item whose metadata is being requested.
 826   * @param string $meta_key        Optional. If present, only the metadata matching
 827   *                                that meta key will be returned. Otherwise, all metadata for the
 828   *                                notification item will be fetched.
 829   * @param bool   $single          Optional. If true, return only the first value of the
 830   *                                specified meta_key. This parameter has no effect if meta_key is not
 831   *                                specified. Default: true.
 832   * @return mixed                  The meta value(s) being requested.
 833   */
 834  function bp_notifications_get_meta( $notification_id = 0, $meta_key = '', $single = true ) {
 835      add_filter( 'query', 'bp_filter_metaid_column_name' );
 836      $retval = get_metadata( 'notification', $notification_id, $meta_key, $single );
 837      remove_filter( 'query', 'bp_filter_metaid_column_name' );
 838  
 839      /**
 840       * Filters the metadata for a specified notification item.
 841       *
 842       * @since 2.3.0
 843       *
 844       * @param mixed  $retval          The meta values for the notification item.
 845       * @param int    $notification_id ID of the notification item.
 846       * @param string $meta_key        Meta key for the value being requested.
 847       * @param bool   $single          Whether to return one matched meta key row or all.
 848       */
 849      return apply_filters( 'bp_notifications_get_meta', $retval, $notification_id, $meta_key, $single );
 850  }
 851  
 852  /**
 853   * Update a piece of notification meta.
 854   *
 855   * @since 1.2.0
 856   *
 857   * @param  int    $notification_id ID of the notification item whose metadata is being
 858   *                                 updated.
 859   * @param  string $meta_key        Key of the metadata being updated.
 860   * @param  mixed  $meta_value      Value to be set.
 861   * @param  mixed  $prev_value      Optional. If specified, only update existing
 862   *                                 metadata entries with the specified value.
 863   *                                 Otherwise, update all entries.
 864   * @return bool|int                Returns false on failure. On successful
 865   *                                 update of existing metadata, returns true. On
 866   *                                 successful creation of new metadata,  returns
 867   *                                 the integer ID of the new metadata row.
 868   */
 869  function bp_notifications_update_meta( $notification_id, $meta_key, $meta_value, $prev_value = '' ) {
 870      add_filter( 'query', 'bp_filter_metaid_column_name' );
 871      $retval = update_metadata( 'notification', $notification_id, $meta_key, $meta_value, $prev_value );
 872      remove_filter( 'query', 'bp_filter_metaid_column_name' );
 873  
 874      return $retval;
 875  }
 876  
 877  /**
 878   * Add a piece of notification metadata.
 879   *
 880   * @since 2.3.0
 881   *
 882   * @param int    $notification_id ID of the notification item.
 883   * @param string $meta_key        Metadata key.
 884   * @param mixed  $meta_value      Metadata value.
 885   * @param bool   $unique          Optional. Whether to enforce a single metadata value
 886   *                                for the given key. If true, and the object already has a value for
 887   *                                the key, no change will be made. Default: false.
 888   * @return int|bool               The meta ID on successful update, false on failure.
 889   */
 890  function bp_notifications_add_meta( $notification_id, $meta_key, $meta_value, $unique = false ) {
 891      add_filter( 'query', 'bp_filter_metaid_column_name' );
 892      $retval = add_metadata( 'notification', $notification_id, $meta_key, $meta_value, $unique );
 893      remove_filter( 'query', 'bp_filter_metaid_column_name' );
 894  
 895      return $retval;
 896  }
 897  
 898  /**
 899   * Finds and exports personal data associated with an email address from the Notifications tables.
 900   *
 901   * @since 4.0.0
 902   *
 903   * @param string $email_address  The users email address.
 904   * @param int    $page           Batch number.
 905   * @return array An array of personal data.
 906   */
 907  function bp_notifications_personal_data_exporter( $email_address, $page ) {
 908      $number = 50;
 909  
 910      $email_address = trim( $email_address );
 911  
 912      $data_to_export = array();
 913  
 914      $user = get_user_by( 'email', $email_address );
 915  
 916      if ( ! $user ) {
 917          return array(
 918              'data' => array(),
 919              'done' => true,
 920          );
 921      }
 922  
 923      $notifications = BP_Notifications_Notification::get( array(
 924          'is_new'   => null,
 925          'per_page' => $number,
 926          'page'     => $page,
 927          'user_id'  => $user->ID,
 928          'order'    => 'DESC',
 929      ) );
 930  
 931      $user_data_to_export = array();
 932  
 933      foreach ( $notifications as $notification ) {
 934          if ( 'xprofile' === $notification->component_name ) {
 935              $component_name = 'profile';
 936          } else {
 937              $component_name = $notification->component_name;
 938          }
 939  
 940          // Format notifications.
 941          if ( isset( buddypress()->{$component_name}->notification_callback ) && is_callable( buddypress()->{$component_name}->notification_callback ) ) {
 942              $content = call_user_func( buddypress()->{$component_name}->notification_callback, $notification->component_action, $notification->item_id, $notification->secondary_item_id, 1, 'string', $notification->id );
 943          } else {
 944              /*
 945               * Compile an array of data to send to filter.
 946               *
 947               * Note that a null value is passed in the slot filled by `total_count` in
 948               * other filter contexts. We don't have enough info here to pass a `total_count`.
 949               */
 950              $ref_array = array(
 951                  $notification->component_action,
 952                  $notification->item_id,
 953                  $notification->secondary_item_id,
 954                  null,
 955                  'string',
 956                  $notification->component_action,
 957                  $component_name,
 958                  $notification->id,
 959              );
 960  
 961              /** This filter is documented in bp-notifications/bp-notifications-functions.php */
 962              $content = apply_filters_ref_array( 'bp_notifications_get_notifications_for_user', $ref_array );
 963          }
 964  
 965          $item_data = array(
 966              array(
 967                  'name'  => __( 'Notification Content', 'buddypress' ),
 968                  'value' => $content,
 969              ),
 970              array(
 971                  'name'  => __( 'Notification Date', 'buddypress' ),
 972                  'value' => $notification->date_notified,
 973              ),
 974              array(
 975                  'name'  => __( 'Status', 'buddypress' ),
 976                  'value' => $notification->is_new ? __( 'Unread', 'buddypress' ) : __( 'Read', 'buddypress' ),
 977              ),
 978          );
 979  
 980          $data_to_export[] = array(
 981              'group_id'    => 'bp_notifications',
 982              'group_label' => __( 'Notifications', 'buddypress' ),
 983              'item_id'     => "bp-notifications-{$notification->id}",
 984              'data'        => $item_data,
 985          );
 986      }
 987  
 988      // Tell core if we have more items to process.
 989      $done = count( $notifications ) < $number;
 990  
 991      return array(
 992          'data' => $data_to_export,
 993          'done' => $done,
 994      );
 995  }


Generated: Sun Oct 13 01:00:54 2024 Cross-referenced by PHPXref 0.7.1