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.


Top ↑

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()


Top ↑

Return

(array|false) Array of menu items, otherwise false.


Top ↑

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 );
}


Top ↑

Changelog

Changelog
VersionDescription
3.0.0Introduced.

The content displayed on this page has been created in part by processing WordPress source code files which are made available under the GPLv2 (or a later version) license by the Free Software Foundation. In addition to this, the content includes user-written examples and information. All material is subject to review and curation by the WPPaste.com community.