| [ Index ] |
PHP Cross Reference of WordPress |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Navigation Menu functions 4 * 5 * @package WordPress 6 * @subpackage Nav_Menus 7 * @since 3.0.0 8 */ 9 10 /** 11 * Returns a navigation menu object. 12 * 13 * @since 3.0.0 14 * 15 * @param int|string|WP_Term $menu Menu ID, slug, name, or object. 16 * @return WP_Term|false False if $menu param isn't supplied or term does not exist, menu object if successful. 17 */ 18 function wp_get_nav_menu_object( $menu ) { 19 $menu_obj = false; 20 21 if ( is_object( $menu ) ) { 22 $menu_obj = $menu; 23 } 24 25 if ( $menu && ! $menu_obj ) { 26 $menu_obj = get_term( $menu, 'nav_menu' ); 27 28 if ( ! $menu_obj ) { 29 $menu_obj = get_term_by( 'slug', $menu, 'nav_menu' ); 30 } 31 32 if ( ! $menu_obj ) { 33 $menu_obj = get_term_by( 'name', $menu, 'nav_menu' ); 34 } 35 } 36 37 if ( ! $menu_obj || is_wp_error( $menu_obj ) ) { 38 $menu_obj = false; 39 } 40 41 /** 42 * Filters the nav_menu term retrieved for wp_get_nav_menu_object(). 43 * 44 * @since 4.3.0 45 * 46 * @param WP_Term|false $menu_obj Term from nav_menu taxonomy, or false if nothing had been found. 47 * @param int|string|WP_Term $menu The menu ID, slug, name, or object passed to wp_get_nav_menu_object(). 48 */ 49 return apply_filters( 'wp_get_nav_menu_object', $menu_obj, $menu ); 50 } 51 52 /** 53 * Check if the given ID is a navigation menu. 54 * 55 * Returns true if it is; false otherwise. 56 * 57 * @since 3.0.0 58 * 59 * @param int|string|WP_Term $menu Menu ID, slug, name, or object of menu to check. 60 * @return bool Whether the menu exists. 61 */ 62 function is_nav_menu( $menu ) { 63 if ( ! $menu ) { 64 return false; 65 } 66 67 $menu_obj = wp_get_nav_menu_object( $menu ); 68 69 if ( 70 $menu_obj && 71 ! is_wp_error( $menu_obj ) && 72 ! empty( $menu_obj->taxonomy ) && 73 'nav_menu' == $menu_obj->taxonomy 74 ) { 75 return true; 76 } 77 78 return false; 79 } 80 81 /** 82 * Registers navigation menu locations for a theme. 83 * 84 * @since 3.0.0 85 * 86 * @global array $_wp_registered_nav_menus 87 * 88 * @param array $locations Associative array of menu location identifiers (like a slug) and descriptive text. 89 */ 90 function register_nav_menus( $locations = array() ) { 91 global $_wp_registered_nav_menus; 92 93 add_theme_support( 'menus' ); 94 95 $_wp_registered_nav_menus = array_merge( (array) $_wp_registered_nav_menus, $locations ); 96 } 97 98 /** 99 * Unregisters a navigation menu location for a theme. 100 * 101 * @since 3.1.0 102 * @global array $_wp_registered_nav_menus 103 * 104 * @param string $location The menu location identifier. 105 * @return bool True on success, false on failure. 106 */ 107 function unregister_nav_menu( $location ) { 108 global $_wp_registered_nav_menus; 109 110 if ( is_array( $_wp_registered_nav_menus ) && isset( $_wp_registered_nav_menus[ $location ] ) ) { 111 unset( $_wp_registered_nav_menus[ $location ] ); 112 if ( empty( $_wp_registered_nav_menus ) ) { 113 _remove_theme_support( 'menus' ); 114 } 115 return true; 116 } 117 return false; 118 } 119 120 /** 121 * Registers a navigation menu location for a theme. 122 * 123 * @since 3.0.0 124 * 125 * @param string $location Menu location identifier, like a slug. 126 * @param string $description Menu location descriptive text. 127 */ 128 function register_nav_menu( $location, $description ) { 129 register_nav_menus( array( $location => $description ) ); 130 } 131 /** 132 * Retrieves all registered navigation menu locations in a theme. 133 * 134 * @since 3.0.0 135 * 136 * @global array $_wp_registered_nav_menus 137 * 138 * @return array Registered navigation menu locations. If none are registered, an empty array. 139 */ 140 function get_registered_nav_menus() { 141 global $_wp_registered_nav_menus; 142 if ( isset( $_wp_registered_nav_menus ) ) { 143 return $_wp_registered_nav_menus; 144 } 145 return array(); 146 } 147 148 /** 149 * Retrieves all registered navigation menu locations and the menus assigned to them. 150 * 151 * @since 3.0.0 152 * 153 * @return array Registered navigation menu locations and the menus assigned them. 154 * If none are registered, an empty array. 155 */ 156 157 function get_nav_menu_locations() { 158 $locations = get_theme_mod( 'nav_menu_locations' ); 159 return ( is_array( $locations ) ) ? $locations : array(); 160 } 161 162 /** 163 * Determines whether a registered nav menu location has a menu assigned to it. 164 * 165 * @since 3.0.0 166 * 167 * @param string $location Menu location identifier. 168 * @return bool Whether location has a menu. 169 */ 170 function has_nav_menu( $location ) { 171 $has_nav_menu = false; 172 173 $registered_nav_menus = get_registered_nav_menus(); 174 if ( isset( $registered_nav_menus[ $location ] ) ) { 175 $locations = get_nav_menu_locations(); 176 $has_nav_menu = ! empty( $locations[ $location ] ); 177 } 178 179 /** 180 * Filters whether a nav menu is assigned to the specified location. 181 * 182 * @since 4.3.0 183 * 184 * @param bool $has_nav_menu Whether there is a menu assigned to a location. 185 * @param string $location Menu location. 186 */ 187 return apply_filters( 'has_nav_menu', $has_nav_menu, $location ); 188 } 189 190 /** 191 * Returns the name of a navigation menu. 192 * 193 * @since 4.9.0 194 * 195 * @param string $location Menu location identifier. 196 * @return string Menu name. 197 */ 198 function wp_get_nav_menu_name( $location ) { 199 $menu_name = ''; 200 201 $locations = get_nav_menu_locations(); 202 203 if ( isset( $locations[ $location ] ) ) { 204 $menu = wp_get_nav_menu_object( $locations[ $location ] ); 205 206 if ( $menu && $menu->name ) { 207 $menu_name = $menu->name; 208 } 209 } 210 211 /** 212 * Filters the navigation menu name being returned. 213 * 214 * @since 4.9.0 215 * 216 * @param string $menu_name Menu name. 217 * @param string $location Menu location identifier. 218 */ 219 return apply_filters( 'wp_get_nav_menu_name', $menu_name, $location ); 220 } 221 222 /** 223 * Determines whether the given ID is a nav menu item. 224 * 225 * @since 3.0.0 226 * 227 * @param int $menu_item_id The ID of the potential nav menu item. 228 * @return bool Whether the given ID is that of a nav menu item. 229 */ 230 function is_nav_menu_item( $menu_item_id = 0 ) { 231 return ( ! is_wp_error( $menu_item_id ) && ( 'nav_menu_item' == get_post_type( $menu_item_id ) ) ); 232 } 233 234 /** 235 * Creates a navigation menu. 236 * 237 * Note that `$menu_name` is expected to be pre-slashed. 238 * 239 * @since 3.0.0 240 * 241 * @param string $menu_name Menu name. 242 * @return int|WP_Error Menu ID on success, WP_Error object on failure. 243 */ 244 function wp_create_nav_menu( $menu_name ) { 245 // expected_slashed ($menu_name) 246 return wp_update_nav_menu_object( 0, array( 'menu-name' => $menu_name ) ); 247 } 248 249 /** 250 * Delete a Navigation Menu. 251 * 252 * @since 3.0.0 253 * 254 * @param int|string|WP_Term $menu Menu ID, slug, name, or object. 255 * @return bool|WP_Error True on success, false or WP_Error object on failure. 256 */ 257 function wp_delete_nav_menu( $menu ) { 258 $menu = wp_get_nav_menu_object( $menu ); 259 if ( ! $menu ) { 260 return false; 261 } 262 263 $menu_objects = get_objects_in_term( $menu->term_id, 'nav_menu' ); 264 if ( ! empty( $menu_objects ) ) { 265 foreach ( $menu_objects as $item ) { 266 wp_delete_post( $item ); 267 } 268 } 269 270 $result = wp_delete_term( $menu->term_id, 'nav_menu' ); 271 272 // Remove this menu from any locations. 273 $locations = get_nav_menu_locations(); 274 foreach ( $locations as $location => $menu_id ) { 275 if ( $menu_id == $menu->term_id ) { 276 $locations[ $location ] = 0; 277 } 278 } 279 set_theme_mod( 'nav_menu_locations', $locations ); 280 281 if ( $result && ! is_wp_error( $result ) ) { 282 283 /** 284 * Fires after a navigation menu has been successfully deleted. 285 * 286 * @since 3.0.0 287 * 288 * @param int $term_id ID of the deleted menu. 289 */ 290 do_action( 'wp_delete_nav_menu', $menu->term_id ); 291 } 292 293 return $result; 294 } 295 296 /** 297 * Save the properties of a menu or create a new menu with those properties. 298 * 299 * Note that `$menu_data` is expected to be pre-slashed. 300 * 301 * @since 3.0.0 302 * 303 * @param int $menu_id The ID of the menu or "0" to create a new menu. 304 * @param array $menu_data The array of menu data. 305 * @return int|WP_Error Menu ID on success, WP_Error object on failure. 306 */ 307 function wp_update_nav_menu_object( $menu_id = 0, $menu_data = array() ) { 308 // expected_slashed ($menu_data) 309 $menu_id = (int) $menu_id; 310 311 $_menu = wp_get_nav_menu_object( $menu_id ); 312 313 $args = array( 314 'description' => ( isset( $menu_data['description'] ) ? $menu_data['description'] : '' ), 315 'name' => ( isset( $menu_data['menu-name'] ) ? $menu_data['menu-name'] : '' ), 316 'parent' => ( isset( $menu_data['parent'] ) ? (int) $menu_data['parent'] : 0 ), 317 'slug' => null, 318 ); 319 320 // double-check that we're not going to have one menu take the name of another 321 $_possible_existing = get_term_by( 'name', $menu_data['menu-name'], 'nav_menu' ); 322 if ( 323 $_possible_existing && 324 ! is_wp_error( $_possible_existing ) && 325 isset( $_possible_existing->term_id ) && 326 $_possible_existing->term_id != $menu_id 327 ) { 328 return new WP_Error( 329 'menu_exists', 330 /* translators: %s: menu name */ 331 sprintf( 332 __( 'The menu name %s conflicts with another menu name. Please try another.' ), 333 '<strong>' . esc_html( $menu_data['menu-name'] ) . '</strong>' 334 ) 335 ); 336 } 337 338 // menu doesn't already exist, so create a new menu 339 if ( ! $_menu || is_wp_error( $_menu ) ) { 340 $menu_exists = get_term_by( 'name', $menu_data['menu-name'], 'nav_menu' ); 341 342 if ( $menu_exists ) { 343 return new WP_Error( 344 'menu_exists', 345 /* translators: %s: menu name */ 346 sprintf( 347 __( 'The menu name %s conflicts with another menu name. Please try another.' ), 348 '<strong>' . esc_html( $menu_data['menu-name'] ) . '</strong>' 349 ) 350 ); 351 } 352 353 $_menu = wp_insert_term( $menu_data['menu-name'], 'nav_menu', $args ); 354 355 if ( is_wp_error( $_menu ) ) { 356 return $_menu; 357 } 358 359 /** 360 * Fires after a navigation menu is successfully created. 361 * 362 * @since 3.0.0 363 * 364 * @param int $term_id ID of the new menu. 365 * @param array $menu_data An array of menu data. 366 */ 367 do_action( 'wp_create_nav_menu', $_menu['term_id'], $menu_data ); 368 369 return (int) $_menu['term_id']; 370 } 371 372 if ( ! $_menu || ! isset( $_menu->term_id ) ) { 373 return 0; 374 } 375 376 $menu_id = (int) $_menu->term_id; 377 378 $update_response = wp_update_term( $menu_id, 'nav_menu', $args ); 379 380 if ( is_wp_error( $update_response ) ) { 381 return $update_response; 382 } 383 384 $menu_id = (int) $update_response['term_id']; 385 386 /** 387 * Fires after a navigation menu has been successfully updated. 388 * 389 * @since 3.0.0 390 * 391 * @param int $menu_id ID of the updated menu. 392 * @param array $menu_data An array of menu data. 393 */ 394 do_action( 'wp_update_nav_menu', $menu_id, $menu_data ); 395 return $menu_id; 396 } 397 398 /** 399 * Save the properties of a menu item or create a new one. 400 * 401 * The menu-item-title, menu-item-description, and menu-item-attr-title are expected 402 * to be pre-slashed since they are passed directly into `wp_insert_post()`. 403 * 404 * @since 3.0.0 405 * 406 * @param int $menu_id The ID of the menu. Required. If "0", makes the menu item a draft orphan. 407 * @param int $menu_item_db_id The ID of the menu item. If "0", creates a new menu item. 408 * @param array $menu_item_data The menu item's data. 409 * @return int|WP_Error The menu item's database ID or WP_Error object on failure. 410 */ 411 function wp_update_nav_menu_item( $menu_id = 0, $menu_item_db_id = 0, $menu_item_data = array() ) { 412 $menu_id = (int) $menu_id; 413 $menu_item_db_id = (int) $menu_item_db_id; 414 415 // make sure that we don't convert non-nav_menu_item objects into nav_menu_item objects 416 if ( ! empty( $menu_item_db_id ) && ! is_nav_menu_item( $menu_item_db_id ) ) { 417 return new WP_Error( 'update_nav_menu_item_failed', __( 'The given object ID is not that of a menu item.' ) ); 418 } 419 420 $menu = wp_get_nav_menu_object( $menu_id ); 421 422 if ( ! $menu && 0 !== $menu_id ) { 423 return new WP_Error( 'invalid_menu_id', __( 'Invalid menu ID.' ) ); 424 } 425 426 if ( is_wp_error( $menu ) ) { 427 return $menu; 428 } 429 430 $defaults = array( 431 'menu-item-db-id' => $menu_item_db_id, 432 'menu-item-object-id' => 0, 433 'menu-item-object' => '', 434 'menu-item-parent-id' => 0, 435 'menu-item-position' => 0, 436 'menu-item-type' => 'custom', 437 'menu-item-title' => '', 438 'menu-item-url' => '', 439 'menu-item-description' => '', 440 'menu-item-attr-title' => '', 441 'menu-item-target' => '', 442 'menu-item-classes' => '', 443 'menu-item-xfn' => '', 444 'menu-item-status' => '', 445 ); 446 447 $args = wp_parse_args( $menu_item_data, $defaults ); 448 449 if ( 0 == $menu_id ) { 450 $args['menu-item-position'] = 1; 451 } elseif ( 0 == (int) $args['menu-item-position'] ) { 452 $menu_items = 0 == $menu_id ? array() : (array) wp_get_nav_menu_items( $menu_id, array( 'post_status' => 'publish,draft' ) ); 453 $last_item = array_pop( $menu_items ); 454 $args['menu-item-position'] = ( $last_item && isset( $last_item->menu_order ) ) ? 1 + $last_item->menu_order : count( $menu_items ); 455 } 456 457 $original_parent = 0 < $menu_item_db_id ? get_post_field( 'post_parent', $menu_item_db_id ) : 0; 458 459 if ( 'custom' === $args['menu-item-type'] ) { 460 // If custom menu item, trim the URL. 461 $args['menu-item-url'] = trim( $args['menu-item-url'] ); 462 } else { 463 /* 464 * If non-custom menu item, then: 465 * - use the original object's URL. 466 * - blank default title to sync with the original object's title. 467 */ 468 469 $args['menu-item-url'] = ''; 470 471 $original_title = ''; 472 if ( 'taxonomy' == $args['menu-item-type'] ) { 473 $original_parent = get_term_field( 'parent', $args['menu-item-object-id'], $args['menu-item-object'], 'raw' ); 474 $original_title = get_term_field( 'name', $args['menu-item-object-id'], $args['menu-item-object'], 'raw' ); 475 } elseif ( 'post_type' == $args['menu-item-type'] ) { 476 477 $original_object = get_post( $args['menu-item-object-id'] ); 478 $original_parent = (int) $original_object->post_parent; 479 $original_title = $original_object->post_title; 480 } elseif ( 'post_type_archive' == $args['menu-item-type'] ) { 481 $original_object = get_post_type_object( $args['menu-item-object'] ); 482 if ( $original_object ) { 483 $original_title = $original_object->labels->archives; 484 } 485 } 486 487 if ( $args['menu-item-title'] == $original_title ) { 488 $args['menu-item-title'] = ''; 489 } 490 491 // hack to get wp to create a post object when too many properties are empty 492 if ( '' == $args['menu-item-title'] && '' == $args['menu-item-description'] ) { 493 $args['menu-item-description'] = ' '; 494 } 495 } 496 497 // Populate the menu item object 498 $post = array( 499 'menu_order' => $args['menu-item-position'], 500 'ping_status' => 0, 501 'post_content' => $args['menu-item-description'], 502 'post_excerpt' => $args['menu-item-attr-title'], 503 'post_parent' => $original_parent, 504 'post_title' => $args['menu-item-title'], 505 'post_type' => 'nav_menu_item', 506 ); 507 508 $update = 0 != $menu_item_db_id; 509 510 // New menu item. Default is draft status 511 if ( ! $update ) { 512 $post['ID'] = 0; 513 $post['post_status'] = 'publish' == $args['menu-item-status'] ? 'publish' : 'draft'; 514 $menu_item_db_id = wp_insert_post( $post ); 515 if ( ! $menu_item_db_id || is_wp_error( $menu_item_db_id ) ) { 516 return $menu_item_db_id; 517 } 518 519 /** 520 * Fires immediately after a new navigation menu item has been added. 521 * 522 * @since 4.4.0 523 * 524 * @see wp_update_nav_menu_item() 525 * 526 * @param int $menu_id ID of the updated menu. 527 * @param int $menu_item_db_id ID of the new menu item. 528 * @param array $args An array of arguments used to update/add the menu item. 529 */ 530 do_action( 'wp_add_nav_menu_item', $menu_id, $menu_item_db_id, $args ); 531 } 532 533 // Associate the menu item with the menu term 534 // Only set the menu term if it isn't set to avoid unnecessary wp_get_object_terms() 535 if ( $menu_id && ( ! $update || ! is_object_in_term( $menu_item_db_id, 'nav_menu', (int) $menu->term_id ) ) ) { 536 wp_set_object_terms( $menu_item_db_id, array( $menu->term_id ), 'nav_menu' ); 537 } 538 539 if ( 'custom' == $args['menu-item-type'] ) { 540 $args['menu-item-object-id'] = $menu_item_db_id; 541 $args['menu-item-object'] = 'custom'; 542 } 543 544 $menu_item_db_id = (int) $menu_item_db_id; 545 546 update_post_meta( $menu_item_db_id, '_menu_item_type', sanitize_key( $args['menu-item-type'] ) ); 547 update_post_meta( $menu_item_db_id, '_menu_item_menu_item_parent', strval( (int) $args['menu-item-parent-id'] ) ); 548 update_post_meta( $menu_item_db_id, '_menu_item_object_id', strval( (int) $args['menu-item-object-id'] ) ); 549 update_post_meta( $menu_item_db_id, '_menu_item_object', sanitize_key( $args['menu-item-object'] ) ); 550 update_post_meta( $menu_item_db_id, '_menu_item_target', sanitize_key( $args['menu-item-target'] ) ); 551 552 $args['menu-item-classes'] = array_map( 'sanitize_html_class', explode( ' ', $args['menu-item-classes'] ) ); 553 $args['menu-item-xfn'] = implode( ' ', array_map( 'sanitize_html_class', explode( ' ', $args['menu-item-xfn'] ) ) ); 554 update_post_meta( $menu_item_db_id, '_menu_item_classes', $args['menu-item-classes'] ); 555 update_post_meta( $menu_item_db_id, '_menu_item_xfn', $args['menu-item-xfn'] ); 556 update_post_meta( $menu_item_db_id, '_menu_item_url', esc_url_raw( $args['menu-item-url'] ) ); 557 558 if ( 0 == $menu_id ) { 559 update_post_meta( $menu_item_db_id, '_menu_item_orphaned', (string) time() ); 560 } elseif ( get_post_meta( $menu_item_db_id, '_menu_item_orphaned' ) ) { 561 delete_post_meta( $menu_item_db_id, '_menu_item_orphaned' ); 562 } 563 564 // Update existing menu item. Default is publish status 565 if ( $update ) { 566 $post['ID'] = $menu_item_db_id; 567 $post['post_status'] = 'draft' == $args['menu-item-status'] ? 'draft' : 'publish'; 568 wp_update_post( $post ); 569 } 570 571 /** 572 * Fires after a navigation menu item has been updated. 573 * 574 * @since 3.0.0 575 * 576 * @see wp_update_nav_menu_item() 577 * 578 * @param int $menu_id ID of the updated menu. 579 * @param int $menu_item_db_id ID of the updated menu item. 580 * @param array $args An array of arguments used to update a menu item. 581 */ 582 do_action( 'wp_update_nav_menu_item', $menu_id, $menu_item_db_id, $args ); 583 584 return $menu_item_db_id; 585 } 586 587 /** 588 * Returns all navigation menu objects. 589 * 590 * @since 3.0.0 591 * @since 4.1.0 Default value of the 'orderby' argument was changed from 'none' 592 * to 'name'. 593 * 594 * @param array $args Optional. Array of arguments passed on to get_terms(). 595 * Default empty array. 596 * @return array Menu objects. 597 */ 598 function wp_get_nav_menus( $args = array() ) { 599 $defaults = array( 600 'hide_empty' => false, 601 'orderby' => 'name', 602 ); 603 $args = wp_parse_args( $args, $defaults ); 604 605 /** 606 * Filters the navigation menu objects being returned. 607 * 608 * @since 3.0.0 609 * 610 * @see get_terms() 611 * 612 * @param array $menus An array of menu objects. 613 * @param array $args An array of arguments used to retrieve menu objects. 614 */ 615 return apply_filters( 'wp_get_nav_menus', get_terms( 'nav_menu', $args ), $args ); 616 } 617 618 /** 619 * Return if a menu item is valid. 620 * 621 * @link https://core.trac.wordpress.org/ticket/13958 622 * 623 * @since 3.2.0 624 * @access private 625 * 626 * @param object $item The menu item to check. 627 * @return bool False if invalid, otherwise true. 628 */ 629 function _is_valid_nav_menu_item( $item ) { 630 return empty( $item->_invalid ); 631 } 632 633 /** 634 * Retrieves all menu items of a navigation menu. 635 * 636 * Note: Most arguments passed to the `$args` parameter – save for 'output_key' – are 637 * specifically for retrieving nav_menu_item posts from get_posts() and may only 638 * indirectly affect the ultimate ordering and content of the resulting nav menu 639 * items that get returned from this function. 640 * 641 * @since 3.0.0 642 * 643 * @staticvar array $fetched 644 * 645 * @param int|string|WP_Term $menu Menu ID, slug, name, or object. 646 * @param array $args { 647 * Optional. Arguments to pass to get_posts(). 648 * 649 * @type string $order How to order nav menu items as queried with get_posts(). Will be ignored 650 * if 'output' is ARRAY_A. Default 'ASC'. 651 * @type string $orderby Field to order menu items by as retrieved from get_posts(). Supply an orderby 652 * field via 'output_key' to affect the output order of nav menu items. 653 * Default 'menu_order'. 654 * @type string $post_type Menu items post type. Default 'nav_menu_item'. 655 * @type string $post_status Menu items post status. Default 'publish'. 656 * @type string $output How to order outputted menu items. Default ARRAY_A. 657 * @type string $output_key Key to use for ordering the actual menu items that get returned. Note that 658 * that is not a get_posts() argument and will only affect output of menu items 659 * processed in this function. Default 'menu_order'. 660 * @type bool $nopaging Whether to retrieve all menu items (true) or paginate (false). Default true. 661 * } 662 * @return false|array $items Array of menu items, otherwise false. 663 */ 664 function wp_get_nav_menu_items( $menu, $args = array() ) { 665 $menu = wp_get_nav_menu_object( $menu ); 666 667 if ( ! $menu ) { 668 return false; 669 } 670 671 static $fetched = array(); 672 673 $items = get_objects_in_term( $menu->term_id, 'nav_menu' ); 674 if ( is_wp_error( $items ) ) { 675 return false; 676 } 677 678 $defaults = array( 679 'order' => 'ASC', 680 'orderby' => 'menu_order', 681 'post_type' => 'nav_menu_item', 682 'post_status' => 'publish', 683 'output' => ARRAY_A, 684 'output_key' => 'menu_order', 685 'nopaging' => true, 686 ); 687 $args = wp_parse_args( $args, $defaults ); 688 $args['include'] = $items; 689 690 if ( ! empty( $items ) ) { 691 $items = get_posts( $args ); 692 } else { 693 $items = array(); 694 } 695 696 // Get all posts and terms at once to prime the caches 697 if ( empty( $fetched[ $menu->term_id ] ) && ! wp_using_ext_object_cache() ) { 698 $fetched[ $menu->term_id ] = true; 699 $posts = array(); 700 $terms = array(); 701 foreach ( $items as $item ) { 702 $object_id = get_post_meta( $item->ID, '_menu_item_object_id', true ); 703 $object = get_post_meta( $item->ID, '_menu_item_object', true ); 704 $type = get_post_meta( $item->ID, '_menu_item_type', true ); 705 706 if ( 'post_type' == $type ) { 707 $posts[ $object ][] = $object_id; 708 } elseif ( 'taxonomy' == $type ) { 709 $terms[ $object ][] = $object_id; 710 } 711 } 712 713 if ( ! empty( $posts ) ) { 714 foreach ( array_keys( $posts ) as $post_type ) { 715 get_posts( 716 array( 717 'post__in' => $posts[ $post_type ], 718 'post_type' => $post_type, 719 'nopaging' => true, 720 'update_post_term_cache' => false, 721 ) 722 ); 723 } 724 } 725 unset( $posts ); 726 727 if ( ! empty( $terms ) ) { 728 foreach ( array_keys( $terms ) as $taxonomy ) { 729 get_terms( 730 $taxonomy, 731 array( 732 'include' => $terms[ $taxonomy ], 733 'hierarchical' => false, 734 ) 735 ); 736 } 737 } 738 unset( $terms ); 739 } 740 741 $items = array_map( 'wp_setup_nav_menu_item', $items ); 742 743 if ( ! is_admin() ) { // Remove invalid items only in front end 744 $items = array_filter( $items, '_is_valid_nav_menu_item' ); 745 } 746 747 if ( ARRAY_A == $args['output'] ) { 748 $items = wp_list_sort( 749 $items, 750 array( 751 $args['output_key'] => 'ASC', 752 ) 753 ); 754 $i = 1; 755 foreach ( $items as $k => $item ) { 756 $items[ $k ]->{$args['output_key']} = $i++; 757 } 758 } 759 760 /** 761 * Filters the navigation menu items being returned. 762 * 763 * @since 3.0.0 764 * 765 * @param array $items An array of menu item post objects. 766 * @param object $menu The menu object. 767 * @param array $args An array of arguments used to retrieve menu item objects. 768 */ 769 return apply_filters( 'wp_get_nav_menu_items', $items, $menu, $args ); 770 } 771 772 /** 773 * Decorates a menu item object with the shared navigation menu item properties. 774 * 775 * Properties: 776 * - ID: The term_id if the menu item represents a taxonomy term. 777 * - attr_title: The title attribute of the link element for this menu item. 778 * - classes: The array of class attribute values for the link element of this menu item. 779 * - db_id: The DB ID of this item as a nav_menu_item object, if it exists (0 if it doesn't exist). 780 * - description: The description of this menu item. 781 * - menu_item_parent: The DB ID of the nav_menu_item that is this item's menu parent, if any. 0 otherwise. 782 * - object: The type of object originally represented, such as "category," "post", or "attachment." 783 * - object_id: The DB ID of the original object this menu item represents, e.g. ID for posts and term_id for categories. 784 * - post_parent: The DB ID of the original object's parent object, if any (0 otherwise). 785 * - post_title: A "no title" label if menu item represents a post that lacks a title. 786 * - target: The target attribute of the link element for this menu item. 787 * - title: The title of this menu item. 788 * - type: The family of objects originally represented, such as "post_type" or "taxonomy." 789 * - type_label: The singular label used to describe this type of menu item. 790 * - url: The URL to which this menu item points. 791 * - xfn: The XFN relationship expressed in the link of this menu item. 792 * - _invalid: Whether the menu item represents an object that no longer exists. 793 * 794 * @since 3.0.0 795 * 796 * @param object $menu_item The menu item to modify. 797 * @return object $menu_item The menu item with standard menu item properties. 798 */ 799 function wp_setup_nav_menu_item( $menu_item ) { 800 if ( isset( $menu_item->post_type ) ) { 801 if ( 'nav_menu_item' == $menu_item->post_type ) { 802 $menu_item->db_id = (int) $menu_item->ID; 803 $menu_item->menu_item_parent = ! isset( $menu_item->menu_item_parent ) ? get_post_meta( $menu_item->ID, '_menu_item_menu_item_parent', true ) : $menu_item->menu_item_parent; 804 $menu_item->object_id = ! isset( $menu_item->object_id ) ? get_post_meta( $menu_item->ID, '_menu_item_object_id', true ) : $menu_item->object_id; 805 $menu_item->object = ! isset( $menu_item->object ) ? get_post_meta( $menu_item->ID, '_menu_item_object', true ) : $menu_item->object; 806 $menu_item->type = ! isset( $menu_item->type ) ? get_post_meta( $menu_item->ID, '_menu_item_type', true ) : $menu_item->type; 807 808 if ( 'post_type' == $menu_item->type ) { 809 $object = get_post_type_object( $menu_item->object ); 810 if ( $object ) { 811 $menu_item->type_label = $object->labels->singular_name; 812 } else { 813 $menu_item->type_label = $menu_item->object; 814 $menu_item->_invalid = true; 815 } 816 817 if ( 'trash' === get_post_status( $menu_item->object_id ) ) { 818 $menu_item->_invalid = true; 819 } 820 821 $menu_item->url = get_permalink( $menu_item->object_id ); 822 823 $original_object = get_post( $menu_item->object_id ); 824 /** This filter is documented in wp-includes/post-template.php */ 825 $original_title = apply_filters( 'the_title', $original_object->post_title, $original_object->ID ); 826 827 if ( '' === $original_title ) { 828 /* translators: %d: ID of a post */ 829 $original_title = sprintf( __( '#%d (no title)' ), $original_object->ID ); 830 } 831 832 $menu_item->title = '' == $menu_item->post_title ? $original_title : $menu_item->post_title; 833 834 } elseif ( 'post_type_archive' == $menu_item->type ) { 835 $object = get_post_type_object( $menu_item->object ); 836 if ( $object ) { 837 $menu_item->title = '' == $menu_item->post_title ? $object->labels->archives : $menu_item->post_title; 838 $post_type_description = $object->description; 839 } else { 840 $menu_item->_invalid = true; 841 $post_type_description = ''; 842 } 843 844 $menu_item->type_label = __( 'Post Type Archive' ); 845 $post_content = wp_trim_words( $menu_item->post_content, 200 ); 846 $post_type_description = '' == $post_content ? $post_type_description : $post_content; 847 $menu_item->url = get_post_type_archive_link( $menu_item->object ); 848 } elseif ( 'taxonomy' == $menu_item->type ) { 849 $object = get_taxonomy( $menu_item->object ); 850 if ( $object ) { 851 $menu_item->type_label = $object->labels->singular_name; 852 } else { 853 $menu_item->type_label = $menu_item->object; 854 $menu_item->_invalid = true; 855 } 856 857 $term_url = get_term_link( (int) $menu_item->object_id, $menu_item->object ); 858 $menu_item->url = ! is_wp_error( $term_url ) ? $term_url : ''; 859 860 $original_title = get_term_field( 'name', $menu_item->object_id, $menu_item->object, 'raw' ); 861 if ( is_wp_error( $original_title ) ) { 862 $original_title = false; 863 } 864 $menu_item->title = '' == $menu_item->post_title ? $original_title : $menu_item->post_title; 865 866 } else { 867 $menu_item->type_label = __( 'Custom Link' ); 868 $menu_item->title = $menu_item->post_title; 869 $menu_item->url = ! isset( $menu_item->url ) ? get_post_meta( $menu_item->ID, '_menu_item_url', true ) : $menu_item->url; 870 } 871 872 $menu_item->target = ! isset( $menu_item->target ) ? get_post_meta( $menu_item->ID, '_menu_item_target', true ) : $menu_item->target; 873 874 /** 875 * Filters a navigation menu item's title attribute. 876 * 877 * @since 3.0.0 878 * 879 * @param string $item_title The menu item title attribute. 880 */ 881 $menu_item->attr_title = ! isset( $menu_item->attr_title ) ? apply_filters( 'nav_menu_attr_title', $menu_item->post_excerpt ) : $menu_item->attr_title; 882 883 if ( ! isset( $menu_item->description ) ) { 884 /** 885 * Filters a navigation menu item's description. 886 * 887 * @since 3.0.0 888 * 889 * @param string $description The menu item description. 890 */ 891 $menu_item->description = apply_filters( 'nav_menu_description', wp_trim_words( $menu_item->post_content, 200 ) ); 892 } 893 894 $menu_item->classes = ! isset( $menu_item->classes ) ? (array) get_post_meta( $menu_item->ID, '_menu_item_classes', true ) : $menu_item->classes; 895 $menu_item->xfn = ! isset( $menu_item->xfn ) ? get_post_meta( $menu_item->ID, '_menu_item_xfn', true ) : $menu_item->xfn; 896 } else { 897 $menu_item->db_id = 0; 898 $menu_item->menu_item_parent = 0; 899 $menu_item->object_id = (int) $menu_item->ID; 900 $menu_item->type = 'post_type'; 901 902 $object = get_post_type_object( $menu_item->post_type ); 903 $menu_item->object = $object->name; 904 $menu_item->type_label = $object->labels->singular_name; 905 906 if ( '' === $menu_item->post_title ) { 907 /* translators: %d: ID of a post */ 908 $menu_item->post_title = sprintf( __( '#%d (no title)' ), $menu_item->ID ); 909 } 910 911 $menu_item->title = $menu_item->post_title; 912 $menu_item->url = get_permalink( $menu_item->ID ); 913 $menu_item->target = ''; 914 915 /** This filter is documented in wp-includes/nav-menu.php */ 916 $menu_item->attr_title = apply_filters( 'nav_menu_attr_title', '' ); 917 918 /** This filter is documented in wp-includes/nav-menu.php */ 919 $menu_item->description = apply_filters( 'nav_menu_description', '' ); 920 $menu_item->classes = array(); 921 $menu_item->xfn = ''; 922 } 923 } elseif ( isset( $menu_item->taxonomy ) ) { 924 $menu_item->ID = $menu_item->term_id; 925 $menu_item->db_id = 0; 926 $menu_item->menu_item_parent = 0; 927 $menu_item->object_id = (int) $menu_item->term_id; 928 $menu_item->post_parent = (int) $menu_item->parent; 929 $menu_item->type = 'taxonomy'; 930 931 $object = get_taxonomy( $menu_item->taxonomy ); 932 $menu_item->object = $object->name; 933 $menu_item->type_label = $object->labels->singular_name; 934 935 $menu_item->title = $menu_item->name; 936 $menu_item->url = get_term_link( $menu_item, $menu_item->taxonomy ); 937 $menu_item->target = ''; 938 $menu_item->attr_title = ''; 939 $menu_item->description = get_term_field( 'description', $menu_item->term_id, $menu_item->taxonomy ); 940 $menu_item->classes = array(); 941 $menu_item->xfn = ''; 942 943 } 944 945 /** 946 * Filters a navigation menu item object. 947 * 948 * @since 3.0.0 949 * 950 * @param object $menu_item The menu item object. 951 */ 952 return apply_filters( 'wp_setup_nav_menu_item', $menu_item ); 953 } 954 955 /** 956 * Get the menu items associated with a particular object. 957 * 958 * @since 3.0.0 959 * 960 * @param int $object_id The ID of the original object. 961 * @param string $object_type The type of object, such as "taxonomy" or "post_type." 962 * @param string $taxonomy If $object_type is "taxonomy", $taxonomy is the name of the tax that $object_id belongs to 963 * @return array The array of menu item IDs; empty array if none; 964 */ 965 function wp_get_associated_nav_menu_items( $object_id = 0, $object_type = 'post_type', $taxonomy = '' ) { 966 $object_id = (int) $object_id; 967 $menu_item_ids = array(); 968 969 $query = new WP_Query; 970 $menu_items = $query->query( 971 array( 972 'meta_key' => '_menu_item_object_id', 973 'meta_value' => $object_id, 974 'post_status' => 'any', 975 'post_type' => 'nav_menu_item', 976 'posts_per_page' => -1, 977 ) 978 ); 979 foreach ( (array) $menu_items as $menu_item ) { 980 if ( isset( $menu_item->ID ) && is_nav_menu_item( $menu_item->ID ) ) { 981 $menu_item_type = get_post_meta( $menu_item->ID, '_menu_item_type', true ); 982 if ( 983 'post_type' == $object_type && 984 'post_type' == $menu_item_type 985 ) { 986 $menu_item_ids[] = (int) $menu_item->ID; 987 } elseif ( 988 'taxonomy' == $object_type && 989 'taxonomy' == $menu_item_type && 990 get_post_meta( $menu_item->ID, '_menu_item_object', true ) == $taxonomy 991 ) { 992 $menu_item_ids[] = (int) $menu_item->ID; 993 } 994 } 995 } 996 997 return array_unique( $menu_item_ids ); 998 } 999 1000 /** 1001 * Callback for handling a menu item when its original object is deleted. 1002 * 1003 * @since 3.0.0 1004 * @access private 1005 * 1006 * @param int $object_id The ID of the original object being trashed. 1007 */ 1008 function _wp_delete_post_menu_item( $object_id = 0 ) { 1009 $object_id = (int) $object_id; 1010 1011 $menu_item_ids = wp_get_associated_nav_menu_items( $object_id, 'post_type' ); 1012 1013 foreach ( (array) $menu_item_ids as $menu_item_id ) { 1014 wp_delete_post( $menu_item_id, true ); 1015 } 1016 } 1017 1018 /** 1019 * Serves as a callback for handling a menu item when its original object is deleted. 1020 * 1021 * @since 3.0.0 1022 * @access private 1023 * 1024 * @param int $object_id Optional. The ID of the original object being trashed. Default 0. 1025 * @param int $tt_id Term taxonomy ID. Unused. 1026 * @param string $taxonomy Taxonomy slug. 1027 */ 1028 function _wp_delete_tax_menu_item( $object_id = 0, $tt_id, $taxonomy ) { 1029 $object_id = (int) $object_id; 1030 1031 $menu_item_ids = wp_get_associated_nav_menu_items( $object_id, 'taxonomy', $taxonomy ); 1032 1033 foreach ( (array) $menu_item_ids as $menu_item_id ) { 1034 wp_delete_post( $menu_item_id, true ); 1035 } 1036 } 1037 1038 /** 1039 * Automatically add newly published page objects to menus with that as an option. 1040 * 1041 * @since 3.0.0 1042 * @access private 1043 * 1044 * @param string $new_status The new status of the post object. 1045 * @param string $old_status The old status of the post object. 1046 * @param object $post The post object being transitioned from one status to another. 1047 */ 1048 function _wp_auto_add_pages_to_menu( $new_status, $old_status, $post ) { 1049 if ( 'publish' != $new_status || 'publish' == $old_status || 'page' != $post->post_type ) { 1050 return; 1051 } 1052 if ( ! empty( $post->post_parent ) ) { 1053 return; 1054 } 1055 $auto_add = get_option( 'nav_menu_options' ); 1056 if ( empty( $auto_add ) || ! is_array( $auto_add ) || ! isset( $auto_add['auto_add'] ) ) { 1057 return; 1058 } 1059 $auto_add = $auto_add['auto_add']; 1060 if ( empty( $auto_add ) || ! is_array( $auto_add ) ) { 1061 return; 1062 } 1063 1064 $args = array( 1065 'menu-item-object-id' => $post->ID, 1066 'menu-item-object' => $post->post_type, 1067 'menu-item-type' => 'post_type', 1068 'menu-item-status' => 'publish', 1069 ); 1070 1071 foreach ( $auto_add as $menu_id ) { 1072 $items = wp_get_nav_menu_items( $menu_id, array( 'post_status' => 'publish,draft' ) ); 1073 if ( ! is_array( $items ) ) { 1074 continue; 1075 } 1076 foreach ( $items as $item ) { 1077 if ( $post->ID == $item->object_id ) { 1078 continue 2; 1079 } 1080 } 1081 wp_update_nav_menu_item( $menu_id, 0, $args ); 1082 } 1083 } 1084 1085 /** 1086 * Delete auto-draft posts associated with the supplied changeset. 1087 * 1088 * @since 4.8.0 1089 * @access private 1090 * 1091 * @param int $post_id Post ID for the customize_changeset. 1092 */ 1093 function _wp_delete_customize_changeset_dependent_auto_drafts( $post_id ) { 1094 $post = get_post( $post_id ); 1095 1096 if ( ! $post || 'customize_changeset' !== $post->post_type ) { 1097 return; 1098 } 1099 1100 $data = json_decode( $post->post_content, true ); 1101 if ( empty( $data['nav_menus_created_posts']['value'] ) ) { 1102 return; 1103 } 1104 remove_action( 'delete_post', '_wp_delete_customize_changeset_dependent_auto_drafts' ); 1105 foreach ( $data['nav_menus_created_posts']['value'] as $stub_post_id ) { 1106 if ( empty( $stub_post_id ) ) { 1107 continue; 1108 } 1109 if ( 'auto-draft' === get_post_status( $stub_post_id ) ) { 1110 wp_delete_post( $stub_post_id, true ); 1111 } elseif ( 'draft' === get_post_status( $stub_post_id ) ) { 1112 wp_trash_post( $stub_post_id ); 1113 delete_post_meta( $stub_post_id, '_customize_changeset_uuid' ); 1114 } 1115 } 1116 add_action( 'delete_post', '_wp_delete_customize_changeset_dependent_auto_drafts' ); 1117 } 1118 1119 /** 1120 * Handle menu config after theme change. 1121 * 1122 * @access private 1123 * @since 4.9.0 1124 */ 1125 function _wp_menus_changed() { 1126 $old_nav_menu_locations = get_option( 'theme_switch_menu_locations', array() ); 1127 $new_nav_menu_locations = get_nav_menu_locations(); 1128 $mapped_nav_menu_locations = wp_map_nav_menu_locations( $new_nav_menu_locations, $old_nav_menu_locations ); 1129 1130 set_theme_mod( 'nav_menu_locations', $mapped_nav_menu_locations ); 1131 delete_option( 'theme_switch_menu_locations' ); 1132 } 1133 1134 /** 1135 * Maps nav menu locations according to assignments in previously active theme. 1136 * 1137 * @since 4.9.0 1138 * 1139 * @param array $new_nav_menu_locations New nav menu locations assignments. 1140 * @param array $old_nav_menu_locations Old nav menu locations assignments. 1141 * @return array Nav menus mapped to new nav menu locations. 1142 */ 1143 function wp_map_nav_menu_locations( $new_nav_menu_locations, $old_nav_menu_locations ) { 1144 $registered_nav_menus = get_registered_nav_menus(); 1145 $new_nav_menu_locations = array_intersect_key( $new_nav_menu_locations, $registered_nav_menus ); 1146 1147 // Short-circuit if there are no old nav menu location assignments to map. 1148 if ( empty( $old_nav_menu_locations ) ) { 1149 return $new_nav_menu_locations; 1150 } 1151 1152 // If old and new theme have just one location, map it and we're done. 1153 if ( 1 === count( $old_nav_menu_locations ) && 1 === count( $registered_nav_menus ) ) { 1154 $new_nav_menu_locations[ key( $registered_nav_menus ) ] = array_pop( $old_nav_menu_locations ); 1155 return $new_nav_menu_locations; 1156 } 1157 1158 $old_locations = array_keys( $old_nav_menu_locations ); 1159 1160 // Map locations with the same slug. 1161 foreach ( $registered_nav_menus as $location => $name ) { 1162 if ( in_array( $location, $old_locations, true ) ) { 1163 $new_nav_menu_locations[ $location ] = $old_nav_menu_locations[ $location ]; 1164 unset( $old_nav_menu_locations[ $location ] ); 1165 } 1166 } 1167 1168 // If there are no old nav menu locations left, then we're done. 1169 if ( empty( $old_nav_menu_locations ) ) { 1170 return $new_nav_menu_locations; 1171 } 1172 1173 /* 1174 * If old and new theme both have locations that contain phrases 1175 * from within the same group, make an educated guess and map it. 1176 */ 1177 $common_slug_groups = array( 1178 array( 'primary', 'menu-1', 'main', 'header', 'navigation', 'top' ), 1179 array( 'secondary', 'menu-2', 'footer', 'subsidiary', 'bottom' ), 1180 array( 'social' ), 1181 ); 1182 1183 // Go through each group... 1184 foreach ( $common_slug_groups as $slug_group ) { 1185 1186 // ...and see if any of these slugs... 1187 foreach ( $slug_group as $slug ) { 1188 1189 // ...and any of the new menu locations... 1190 foreach ( $registered_nav_menus as $new_location => $name ) { 1191 1192 // ...actually match! 1193 if ( is_string( $new_location ) && false === stripos( $new_location, $slug ) && false === stripos( $slug, $new_location ) ) { 1194 continue; 1195 } elseif ( is_numeric( $new_location ) && $new_location !== $slug ) { 1196 continue; 1197 } 1198 1199 // Then see if any of the old locations... 1200 foreach ( $old_nav_menu_locations as $location => $menu_id ) { 1201 1202 // ...and any slug in the same group... 1203 foreach ( $slug_group as $slug ) { 1204 1205 // ... have a match as well. 1206 if ( is_string( $location ) && false === stripos( $location, $slug ) && false === stripos( $slug, $location ) ) { 1207 continue; 1208 } elseif ( is_numeric( $location ) && $location !== $slug ) { 1209 continue; 1210 } 1211 1212 // Make sure this location wasn't mapped and removed previously. 1213 if ( ! empty( $old_nav_menu_locations[ $location ] ) ) { 1214 1215 // We have a match that can be mapped! 1216 $new_nav_menu_locations[ $new_location ] = $old_nav_menu_locations[ $location ]; 1217 1218 // Remove the mapped location so it can't be mapped again. 1219 unset( $old_nav_menu_locations[ $location ] ); 1220 1221 // Go back and check the next new menu location. 1222 continue 3; 1223 } 1224 } // endforeach ( $slug_group as $slug ) 1225 } // endforeach ( $old_nav_menu_locations as $location => $menu_id ) 1226 } // endforeach foreach ( $registered_nav_menus as $new_location => $name ) 1227 } // endforeach ( $slug_group as $slug ) 1228 } // endforeach ( $common_slug_groups as $slug_group ) 1229 1230 return $new_nav_menu_locations; 1231 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Wed Jul 24 01:00:02 2019 | Cross-referenced by PHPXref 0.7.1 |