| [ Index ] |
PHP Cross Reference of BuddyPress |
[Summary view] [Print] [Text view]
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 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Tue Apr 16 01:01:07 2024 | Cross-referenced by PHPXref 0.7.1 |