[ Index ]

PHP Cross Reference of BuddyPress

title

Body

[close]

/src/bp-core/ -> bp-core-taxonomy.php (source)

   1  <?php
   2  /**
   3   * BuddyPress taxonomy functions.
   4   *
   5   * Most BuddyPress taxonomy functions are wrappers for their WordPress counterparts.
   6   * Because BuddyPress can be activated in various ways in a network environment, we
   7   * must switch to the root blog before using the WP functions.
   8   *
   9   * @package BuddyPress
  10   * @subpackage Core
  11   * @since 2.2.0
  12   */
  13  
  14  // Exit if accessed directly.
  15  defined( 'ABSPATH' ) || exit;
  16  
  17  /**
  18   * Returns default BuddyPress taxonomies.
  19   *
  20   * @since 7.0.0
  21   *
  22   * @return array The BuddyPress default taxonomies.
  23   */
  24  function bp_get_default_taxonomies() {
  25      $taxonomies = array(
  26          // Member Type.
  27          bp_get_member_type_tax_name() => array(
  28              'object'    => 'user',
  29              'component' => 'members',
  30              'args'      => bp_get_member_type_tax_args(),
  31          ),
  32          // Email type.
  33          bp_get_email_tax_type()       => array(
  34              'object'    => bp_get_email_post_type(),
  35              'component' => 'core',
  36              'args'      => bp_get_email_tax_type_args(),
  37          ),
  38      );
  39  
  40      /**
  41       * This filter should only be used by built-in BuddyPress Components.
  42       *
  43       * @since 7.0.0
  44       *
  45       * @param array $taxonomies The taxonomy arguments used for WordPress registration.
  46       */
  47      return apply_filters( 'bp_get_default_taxonomies', $taxonomies );
  48  }
  49  
  50  /**
  51   * Register our default taxonomies.
  52   *
  53   * @since 2.2.0
  54   */
  55  function bp_register_default_taxonomies() {
  56      $taxonomies = bp_get_default_taxonomies();
  57  
  58      foreach ( $taxonomies as $taxonomy_name => $taxonomy_params ) {
  59          if ( ! isset( $taxonomy_params['object'] ) || ! isset( $taxonomy_params['args'] ) ) {
  60              continue;
  61          }
  62  
  63          register_taxonomy(
  64              $taxonomy_name,
  65              $taxonomy_params['object'],
  66              $taxonomy_params['args']
  67          );
  68      }
  69  }
  70  add_action( 'bp_register_taxonomies', 'bp_register_default_taxonomies' );
  71  
  72  /**
  73   * Gets the ID of the site that BP should use for taxonomy term storage.
  74   *
  75   * Defaults to the root blog ID.
  76   *
  77   * @since 2.6.0
  78   *
  79   * @param string $taxonomy Taxonomy slug to check for.
  80   * @return int
  81   */
  82  function bp_get_taxonomy_term_site_id( $taxonomy = '' ) {
  83      $site_id = bp_get_root_blog_id();
  84  
  85      /**
  86       * Filters the ID of the site where BP should store taxonomy terms.
  87       *
  88       * @since 2.6.0
  89       *
  90       * @param int    $site_id  Site ID to cehck for.
  91       * @param string $taxonomy Taxonomy slug to check for.
  92       */
  93      return (int) apply_filters( 'bp_get_taxonomy_term_site_id', $site_id, $taxonomy );
  94  }
  95  
  96  /**
  97   * Set taxonomy terms on a BuddyPress object.
  98   *
  99   * @since 2.2.0
 100   *
 101   * @see wp_set_object_terms() for a full description of function and parameters.
 102   *
 103   * @param int          $object_id Object ID.
 104   * @param string|array $terms     Term or terms to set.
 105   * @param string       $taxonomy  Taxonomy name.
 106   * @param bool         $append    Optional. True to append terms to existing terms. Default: false.
 107   * @return array Array of term taxonomy IDs.
 108   */
 109  function bp_set_object_terms( $object_id, $terms, $taxonomy, $append = false ) {
 110      $site_id = bp_get_taxonomy_term_site_id( $taxonomy );
 111  
 112      $switched = false;
 113      if ( $site_id !== get_current_blog_id() ) {
 114          switch_to_blog( $site_id );
 115          bp_register_taxonomies();
 116          $switched = true;
 117      }
 118  
 119      $tt_ids = wp_set_object_terms( $object_id, $terms, $taxonomy, $append );
 120  
 121      if ( $switched ) {
 122          restore_current_blog();
 123      }
 124  
 125      /**
 126       * Fires when taxonomy terms have been set on BuddyPress objects.
 127       *
 128       * @since 2.7.0
 129       *
 130       * @param int    $object_id Object ID.
 131       * @param array  $terms     Term or terms to remove.
 132       * @param array  $tt_ids    Array of term taxonomy IDs.
 133       * @param string $taxonomy  Taxonomy name.
 134       */
 135      do_action( 'bp_set_object_terms', $object_id, $terms, $tt_ids, $taxonomy );
 136  
 137      return $tt_ids;
 138  }
 139  
 140  /**
 141   * Get taxonomy terms for a BuddyPress object.
 142   *
 143   * @since 2.2.0
 144   *
 145   * @see wp_get_object_terms() for a full description of function and parameters.
 146   *
 147   * @param int|array    $object_ids ID or IDs of objects.
 148   * @param string|array $taxonomies Name or names of taxonomies to match.
 149   * @param array        $args       See {@see wp_get_object_terms()}.
 150   * @return array
 151   */
 152  function bp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {
 153      // Different taxonomies must be stored on different sites.
 154      $taxonomy_site_map = array();
 155      foreach ( (array) $taxonomies as $taxonomy ) {
 156          $taxonomy_site_id = bp_get_taxonomy_term_site_id( $taxonomy );
 157          $taxonomy_site_map[ $taxonomy_site_id ][] = $taxonomy;
 158      }
 159  
 160      $retval = array();
 161      foreach ( $taxonomy_site_map as $taxonomy_site_id => $site_taxonomies ) {
 162          $switched = false;
 163          if ( $taxonomy_site_id !== get_current_blog_id() ) {
 164              switch_to_blog( $taxonomy_site_id );
 165              bp_register_taxonomies();
 166              $switched = true;
 167          }
 168  
 169          $site_terms = wp_get_object_terms( $object_ids, $site_taxonomies, $args );
 170          $retval     = array_merge( $retval, $site_terms );
 171  
 172          if ( $switched ) {
 173              restore_current_blog();
 174          }
 175      }
 176  
 177      return $retval;
 178  }
 179  
 180  /**
 181   * Remove taxonomy terms on a BuddyPress object.
 182   *
 183   * @since 2.3.0
 184   *
 185   * @see wp_remove_object_terms() for a full description of function and parameters.
 186   *
 187   * @param int          $object_id Object ID.
 188   * @param string|array $terms     Term or terms to remove.
 189   * @param string       $taxonomy  Taxonomy name.
 190   * @return bool|WP_Error True on success, false or WP_Error on failure.
 191   */
 192  function bp_remove_object_terms( $object_id, $terms, $taxonomy ) {
 193      $site_id = bp_get_taxonomy_term_site_id( $taxonomy );
 194  
 195      $switched = false;
 196      if ( $site_id !== get_current_blog_id() ) {
 197          switch_to_blog( $site_id );
 198          bp_register_taxonomies();
 199          $switched = true;
 200      }
 201  
 202      $retval = wp_remove_object_terms( $object_id, $terms, $taxonomy );
 203  
 204      if ( $switched ) {
 205          restore_current_blog();
 206      }
 207  
 208      /**
 209       * Fires when taxonomy terms have been removed from BuddyPress objects.
 210       *
 211       * @since 2.7.0
 212       *
 213       * @param int    $object_id Object ID.
 214       * @param array  $terms     Term or terms to remove.
 215       * @param string $taxonomy  Taxonomy name.
 216       */
 217      do_action( 'bp_remove_object_terms', $object_id, $terms, $taxonomy );
 218  
 219      return $retval;
 220  }
 221  
 222  /**
 223   * Retrieve IDs of objects in valid taxonomies and terms for BuddyPress-related taxonomies.
 224   *
 225   * Note that object IDs are from the `bp_get_taxonomy_term_site_id()`, which on some
 226   * multisite configurations may not be the same as the current site.
 227   *
 228   * @since 2.7.0
 229   *
 230   * @see get_objects_in_term() for a full description of function and parameters.
 231   *
 232   * @param int|array    $term_ids   Term id or array of term ids of terms that will be used.
 233   * @param string|array $taxonomies String of taxonomy name or Array of string values of taxonomy names.
 234   * @param array|string $args       Change the order of the object_ids, either ASC or DESC.
 235   *
 236   * @return WP_Error|array If the taxonomy does not exist, then WP_Error will be returned. On success,
 237   *                        the array can be empty, meaning that there are no $object_ids found. When
 238   *                        object IDs are found, an array of those IDs will be returned.
 239   */
 240  function bp_get_objects_in_term( $term_ids, $taxonomies, $args = array() ) {
 241      // Different taxonomies may be stored on different sites.
 242      $taxonomy_site_map = array();
 243      foreach ( (array) $taxonomies as $taxonomy ) {
 244          $taxonomy_site_id = bp_get_taxonomy_term_site_id( $taxonomy );
 245          $taxonomy_site_map[ $taxonomy_site_id ][] = $taxonomy;
 246      }
 247  
 248      $retval = array();
 249      foreach ( $taxonomy_site_map as $taxonomy_site_id => $site_taxonomies ) {
 250          $switched = false;
 251          if ( $taxonomy_site_id !== get_current_blog_id() ) {
 252              switch_to_blog( $taxonomy_site_id );
 253              bp_register_taxonomies();
 254              $switched = true;
 255          }
 256  
 257          $site_objects = get_objects_in_term( $term_ids, $site_taxonomies, $args );
 258          $retval       = array_merge( $retval, $site_objects );
 259  
 260          if ( $switched ) {
 261              restore_current_blog();
 262          }
 263      }
 264  
 265      return $retval;
 266  }
 267  
 268  /**
 269   * Get term data for terms in BuddyPress taxonomies.
 270   *
 271   * Note that term data is from the `bp_get_taxonomy_term_site_id()`, which on some
 272   * multisite configurations may not be the same as the current site.
 273   *
 274   * @since 2.7.0
 275   *
 276   * @see get_term_by() for a full description of function and parameters.
 277   *
 278   * @param string     $field    Either 'slug', 'name', 'id' (term_id), or 'term_taxonomy_id'
 279   * @param string|int $value    Search for this term value
 280   * @param string     $taxonomy Taxonomy name. Optional, if `$field` is 'term_taxonomy_id'.
 281   * @param string     $output   Constant OBJECT, ARRAY_A, or ARRAY_N
 282   * @param string     $filter   Optional, default is raw or no WordPress defined filter will applied.
 283   *
 284   * @return WP_Term|bool WP_Term instance on success. Will return false if `$taxonomy` does not exist
 285   *                      or `$term` was not found.
 286   */
 287  function bp_get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
 288      $site_id = bp_get_taxonomy_term_site_id( $taxonomy );
 289  
 290      $switched = false;
 291      if ( $site_id !== get_current_blog_id() ) {
 292          switch_to_blog( $site_id );
 293          bp_register_taxonomies();
 294          $switched = true;
 295      }
 296  
 297      $term = get_term_by( $field, $value, $taxonomy, $output, $filter );
 298  
 299      if ( $switched ) {
 300          restore_current_blog();
 301      }
 302  
 303      return $term;
 304  }
 305  
 306  /**
 307   * Add a new taxonomy term to the database.
 308   *
 309   * @since 7.0.0
 310   *
 311   * @param string $term     The BP term name to add.
 312   * @param string $taxonomy The BP taxonomy to which to add the BP term.
 313   * @param array  $args {
 314   *     Optional. Array of arguments for inserting a BP term.
 315   *     @type string $description The term description. Default empty string.
 316   *     @type string $slug        The term slug to use. Default empty string.
 317   *     @type array  $metas       The term metas to add. Default empty array.
 318   * }
 319   * @return array|WP_Error An array containing the `term_id` and `term_taxonomy_id`,
 320   *                        WP_Error otherwise.
 321   */
 322  function bp_insert_term( $term, $taxonomy = '', $args = array() ) {
 323      if ( ! taxonomy_exists( $taxonomy ) ) {
 324          return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.', 'buddypress' ) );
 325      }
 326  
 327      $site_id = bp_get_taxonomy_term_site_id( $taxonomy );
 328  
 329      $switched = false;
 330      if ( $site_id !== get_current_blog_id() ) {
 331          switch_to_blog( $site_id );
 332          bp_register_taxonomies();
 333          $switched = true;
 334      }
 335  
 336      $term_metas = array();
 337      if ( isset( $args['metas'] ) ) {
 338          $term_metas = (array) $args['metas'];
 339          unset( $args['metas'] );
 340      }
 341  
 342      /**
 343       * Fires before a BP Term is added to the database.
 344       *
 345       * @since 7.0.0
 346       *
 347       * @param string $term     The BP term name to add.
 348       * @param string $taxonomy The BP taxonomy to which to add the term.
 349       * @param array  $args     Array of arguments for inserting a BP term.
 350       */
 351      do_action( 'bp_before_insert_term', $term, $taxonomy, $args );
 352  
 353      $tt_id = wp_insert_term( $term, $taxonomy, $args );
 354  
 355      if ( is_wp_error( $tt_id ) ) {
 356          return $tt_id;
 357      }
 358  
 359      $term_id = reset( $tt_id );
 360  
 361      if ( $term_metas ) {
 362          bp_update_type_metadata( $term_id, $taxonomy, $term_metas );
 363      }
 364  
 365      if ( $switched ) {
 366          restore_current_blog();
 367      }
 368  
 369      /**
 370       * Fires when taxonomy terms have been set on BuddyPress objects.
 371       *
 372       * @since 7.0.0
 373       *
 374       * @param array  $tt_ids    An array containing the `term_id` and `term_taxonomy_id`.
 375       * @param string $taxonomy  Taxonomy name.
 376       * @param array  $term_metas The term metadata.
 377       */
 378      do_action( 'bp_insert_term', $tt_id, $taxonomy, $term_metas );
 379  
 380      return $tt_id;
 381  }
 382  
 383  /**
 384   * Get taxonomy BP Terms from the database.
 385   *
 386   * @since 7.0.0
 387   *
 388   * @param array  $args {
 389   *     Array of arguments to query BP Terms.
 390   *     @see `get_terms()` for full description of arguments in case of a member type.
 391   * }
 392   * @return array The list of terms matching arguments.
 393   */
 394  function bp_get_terms( $args = array() ) {
 395      $args = bp_parse_args(
 396          $args,
 397          array(
 398              'taxonomy'   => '',
 399              'number'     => '',
 400              'hide_empty' => false,
 401          ),
 402          'get_terms'
 403      );
 404  
 405      if ( ! $args['taxonomy'] ) {
 406          return array();
 407      }
 408  
 409      $site_id = bp_get_taxonomy_term_site_id( $args['taxonomy'] );
 410  
 411      $switched = false;
 412      if ( $site_id !== get_current_blog_id() ) {
 413          switch_to_blog( $site_id );
 414          bp_register_taxonomies();
 415          $switched = true;
 416      }
 417  
 418      $terms = get_terms( $args );
 419  
 420      if ( $switched ) {
 421          restore_current_blog();
 422      }
 423  
 424      /**
 425       * Filter here to modify the BP Terms found into the database.
 426       *
 427       * @since 7.0.0
 428       *
 429       * @param array $terms The list of terms matching arguments.
 430       * @param array $args  Array of arguments used to query BP Terms.
 431       */
 432      return apply_filters(
 433          'bp_get_terms',
 434          $terms,
 435          $args
 436      );
 437  }
 438  
 439  /**
 440   * Deletes a BP Term.
 441   *
 442   * @since 7.0.0
 443   *
 444   * @param int     $term_id  The BP Term ID. Required.
 445   * @param string  $taxonomy The BP Taxonomy Name. Required.
 446   * @return bool|WP_Error True on success, WP_Error on failure.
 447   */
 448  function bp_delete_term( $term_id = 0, $taxonomy = '' ) {
 449      if ( ! $term_id || ! $taxonomy ) {
 450          return new WP_Error( 'missing_arguments', __( 'Sorry, the term ID and the taxonomy are required arguments.', 'buddypress' ) );
 451      }
 452  
 453      $site_id = bp_get_taxonomy_term_site_id( $taxonomy );
 454  
 455      $switched = false;
 456      if ( $site_id !== get_current_blog_id() ) {
 457          switch_to_blog( $site_id );
 458          bp_register_taxonomies();
 459          $switched = true;
 460      }
 461  
 462      /**
 463       * Fires before a BP Term is deleted from the database.
 464       *
 465       * @since 7.0.0
 466       *
 467       * @param int    $term_id  The BP Term ID.
 468       * @param string $taxonomy The BP Taxonomy Name.
 469       */
 470      do_action( 'bp_before_delete_term', $term_id, $taxonomy );
 471  
 472      $deleted = wp_delete_term( $term_id, $taxonomy );
 473  
 474      if ( $switched ) {
 475          restore_current_blog();
 476      }
 477  
 478      if ( is_wp_error( $deleted ) ) {
 479          return $deleted;
 480      }
 481  
 482      if ( false === $deleted ) {
 483          return new WP_Error( 'inexistant_term', __( 'Sorry, the term does not exist.', 'buddypress' ) );
 484      }
 485  
 486      if ( 0 === $deleted ) {
 487          return new WP_Error( 'default_term', __( 'Sorry, the default term cannot be deleted.', 'buddypress' ) );
 488      }
 489  
 490      /**
 491       * Fires once a BP Term has been deleted from the database.
 492       *
 493       * @since 7.0.0
 494       *
 495       * @param boolean $deleted True.
 496       * @param int     $term_id  The deleted BP Term ID.
 497       * @param string  $taxonomy The BP Taxonomy Name of the deleted BP Term ID.
 498       */
 499      do_action( 'bp_delete_term', $deleted, $term_id, $taxonomy );
 500  
 501      return $deleted;
 502  }


Generated: Sat Dec 14 01:00:55 2024 Cross-referenced by PHPXref 0.7.1