wp_get_nav_menu_items( int|string|WP_Term $menu, array $args = array() ): array|false

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$menuint|string|WP_Term

Menu ID, slug, name, or object.

$argsarrayoptional

Arguments to pass to get_posts().Default: array()

• $orderstringdefault: 'ASC'

  How to order nav menu items as queried with get_posts(). Will be ignored if 'output' is ARRAY_A.

• $orderbystringdefault: 'menu_order'

  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.

• $post_typestringdefault: 'nav_menu_item'

  Menu items post type.

• $post_statusstringdefault: 'publish'

  Menu items post status.

• $outputstringdefault: ARRAY_A

  How to order outputted menu items.

• $output_keystringdefault: 'menu_order'

  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.

• $nopagingbooldefault: true

  Whether to retrieve all menu items (true) or paginate (false).

• $update_menu_item_cachebooldefault: true

  Whether to update the menu item cache.

Return value

array|false

Array of menu items, otherwise false.

Performance profile

How much work a call to wp_get_nav_menu_items() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via get_posts().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

8–75

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 85.

Plugin surface

1 hook

Third-party callbacks on 'wp_get_nav_menu_items' run inside this call, and their cost is not bounded by anything here.

Called by

9

9 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• querycontent queryget_posts()called directly
• hookthird-party callbacksapply_filters()called directly

Further down the call graph this can also reach option, cache, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 10 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_get_nav_menu_items() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 1

One hook fires while wp_get_nav_menu_items() runs, in this order:

1. 1
   apply_filters( wp_get_nav_menu_items )filterline 777 (+65 into the body)

   Filters the navigation menu items being returned.

Uses · 7

• wp_get_nav_menu_object()Returns a navigation menu object.
• taxonomy_exists()Determines whether the taxonomy name exists.
• wp_parse_args()Merges user defined arguments into defaults array.
• get_posts()Retrieves an array of the latest posts, or posts matching the given criteria.
• is_admin()Determines whether the current request is for an administrative interface page.
• wp_list_sort()Sorts an array of objects or arrays based on one or more orderby arguments.
• apply_filters()Calls the callback functions that have been added to a filter hook.

Used by · 9

• WP_Classic_To_Block_Menu_Converter::convert()Converts a Classic Menu to blocks.
• WP_Customize_Nav_Menus::customize_register()Adds the customizer settings and controls.
• _wp_auto_add_pages_to_menu()Automatically add newly published page objects to menus with that as an option.
• block_core_navigation_get_classic_menu_fallback_blocks()Converts a classic navigation to blocks.
• block_core_navigation_get_menu_items_at_location()Returns the menu items for a WordPress menu location.
• wp_get_nav_menu_to_edit()Returns the menu formatted to edit.
• wp_nav_menu()Displays a navigation menu.
• wp_nav_menu_update_menu_items()Saves nav menu items.
• wp_update_nav_menu_item()Saves the properties of a menu item or create a new one.

Source code

View on Trac ↗View on GitHub ↗

712function wp_get_nav_menu_items( $menu, $args = array() ) {713	$menu = wp_get_nav_menu_object( $menu );714 715	if ( ! $menu ) {716		return false;717	}718 719	if ( ! taxonomy_exists( 'nav_menu' ) ) {720		return false;721	}722 723	$defaults = array(724		'order'                  => 'ASC',725		'orderby'                => 'menu_order',726		'post_type'              => 'nav_menu_item',727		'post_status'            => 'publish',728		'output'                 => ARRAY_A,729		'output_key'             => 'menu_order',730		'nopaging'               => true,731		'update_menu_item_cache' => true,732		'tax_query'              => array(733			array(734				'taxonomy' => 'nav_menu',735				'field'    => 'term_taxonomy_id',736				'terms'    => $menu->term_taxonomy_id,737			),738		),739	);740	$args     = wp_parse_args( $args, $defaults );741	if ( $menu->count > 0 ) {742		$items = get_posts( $args );743	} else {744		$items = array();745	}746 747	$items = array_map( 'wp_setup_nav_menu_item', $items );748 749	if ( ! is_admin() ) { // Remove invalid items only on front end.750		$items = array_filter( $items, '_is_valid_nav_menu_item' );751	}752 753	if ( ARRAY_A === $args['output'] ) {754		$items = wp_list_sort(755			$items,756			array(757				$args['output_key'] => 'ASC',758			)759		);760 761		$i = 1;762 763		foreach ( $items as $k => $item ) {764			$items[ $k ]->{$args['output_key']} = $i++;765		}766	}767 768	/**769	 * Filters the navigation menu items being returned.770	 *771	 * @since 3.0.0772	 *773	 * @param array  $items An array of menu item post objects.774	 * @param object $menu  The menu object.775	 * @param array  $args  An array of arguments used to retrieve menu item objects.776	 */777	return apply_filters( 'wp_get_nav_menu_items', $items, $menu, $args );778}

Changelog

Introduced in 3.0.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/nav-menu.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.