wp_get_nav_menu_items() WordPress Function
The wp_get_nav_menu_items() function allows you to get the menu items for a given menu. This is useful if you want to programmatically output a menu in your theme.
wp_get_nav_menu_items( int|string|WP_Term $menu, array $args = array() ) #
Retrieves all menu items of a navigation menu.
Description
Note: Most arguments passed to the $args
parameter – save for ‘output_key’ – are specifically for retrieving nav_menu_item posts from get_posts() and may only indirectly affect the ultimate ordering and content of the resulting nav menu items that get returned from this function.
Parameters
- $menu
(int|string|WP_Term)(Required)Menu ID, slug, name, or object.
- $args
(array)(Optional)Arguments to pass to get_posts().
- 'order'
(string) How to order nav menu items as queried with get_posts(). Will be ignored if 'output' is ARRAY_A. Default 'ASC'. - 'orderby'
(string) Field to order menu items by as retrieved from get_posts(). Supply an orderby field via 'output_key' to affect the output order of nav menu items. Default 'menu_order'. - 'post_type'
(string) Menu items post type. Default 'nav_menu_item'. - 'post_status'
(string) Menu items post status. Default 'publish'. - 'output'
(string) How to order outputted menu items. Default ARRAY_A. - 'output_key'
(string) Key to use for ordering the actual menu items that get returned. Note that that is not a get_posts() argument and will only affect output of menu items processed in this function. Default 'menu_order'. - 'nopaging'
(bool) Whether to retrieve all menu items (true) or paginate (false). Default true.
Default value: array()
- 'order'
Return
(array|false) Array of menu items, otherwise false.
Source
File: wp-includes/nav-menu.php
function wp_get_nav_menu_items( $menu, $args = array() ) { $menu = wp_get_nav_menu_object( $menu ); if ( ! $menu ) { return false; } static $fetched = array(); if ( ! taxonomy_exists( 'nav_menu' ) ) { return false; } $defaults = array( 'order' => 'ASC', 'orderby' => 'menu_order', 'post_type' => 'nav_menu_item', 'post_status' => 'publish', 'output' => ARRAY_A, 'output_key' => 'menu_order', 'nopaging' => true, 'tax_query' => array( array( 'taxonomy' => 'nav_menu', 'field' => 'term_taxonomy_id', 'terms' => $menu->term_taxonomy_id, ), ), ); $args = wp_parse_args( $args, $defaults ); if ( $menu->count > 0 ) { $items = get_posts( $args ); } else { $items = array(); } // Prime posts and terms caches. if ( empty( $fetched[ $menu->term_id ] ) ) { $fetched[ $menu->term_id ] = true; $post_ids = array(); $term_ids = array(); foreach ( $items as $item ) { $object_id = get_post_meta( $item->ID, '_menu_item_object_id', true ); $type = get_post_meta( $item->ID, '_menu_item_type', true ); if ( 'post_type' === $type ) { $post_ids[] = (int) $object_id; } elseif ( 'taxonomy' === $type ) { $term_ids[] = (int) $object_id; } } if ( ! empty( $post_ids ) ) { _prime_post_caches( $post_ids, false ); } unset( $post_ids ); if ( ! empty( $term_ids ) ) { _prime_term_caches( $term_ids ); } unset( $term_ids ); } $items = array_map( 'wp_setup_nav_menu_item', $items ); if ( ! is_admin() ) { // Remove invalid items only on front end. $items = array_filter( $items, '_is_valid_nav_menu_item' ); } if ( ARRAY_A === $args['output'] ) { $items = wp_list_sort( $items, array( $args['output_key'] => 'ASC', ) ); $i = 1; foreach ( $items as $k => $item ) { $items[ $k ]->{$args['output_key']} = $i++; } } /** * Filters the navigation menu items being returned. * * @since 3.0.0 * * @param array $items An array of menu item post objects. * @param object $menu The menu object. * @param array $args An array of arguments used to retrieve menu item objects. */ return apply_filters( 'wp_get_nav_menu_items', $items, $menu, $args ); }
Expand full source codeCollapse full source codeView on TracView on GitHub
Changelog
Version | Description |
---|---|
3.0.0 | Introduced. |