Menus: Do not gate wp_get_nav_menu_items() on the menu term count - #13596

Trac ticket: https://core.trac.wordpress.org/ticket/66102

Problem

wp_get_nav_menu_items() short-circuits before running its item query whenever the menu term's count is 0:

$args = wp_parse_args( $args, $defaults );
if ( $menu->count > 0 ) {
        $items = get_posts( $args );
} else {
        $items = array();
}

$menu->count is not a safe proxy for "no items match these args":

• It counts published items only. _update_post_term_count() counts posts with post_status = 'publish' (the default of the update_post_term_count_statuses filter), so a menu whose items are all draft or trash reports count = 0 even though a caller querying 'draft', 'any', 'publish,draft', or 'trash' has matching items.
• It can be stale. wp_defer_term_counting( true ) leaves the count at 0 while items are already attached, and wp_get_nav_menu_object() returns a passed WP_Term object verbatim, so a caller holding a term snapshot taken before items were added is gated as well.

post_status is a documented argument of wp_get_nav_menu_items(), so all of the following return array() while get_posts() with the same arguments returns real items:

• a draft-only menu queried with post_status 'draft', 'any', or 'publish,draft';
• a trash-only menu queried with 'trash' (trashing the last published item returns the count to 0);
• a published item attached while term counting is deferred — hidden even from the default 'publish' query;
• any item hidden behind a stale WP_Term snapshot passed as $menu.

In-core consequences

• Colliding menu_order. wp_update_nav_menu_item() positions a new item by querying 'publish,draft' items and using 1 + the last item's menu_order. On a menu with no published items — e.g. one being assembled as drafts — the gate empties the list, so the new item gets menu_order = 0; every subsequent item collides at position 0 instead of being appended.
• Duplicate auto-added pages. _wp_auto_add_pages_to_menu() queries the 'publish,draft' item list to skip pages already in the menu. On a menu with no published items the check sees an empty list and inserts a second item for the same page.
• Other in-core callers requesting non-default statuses are affected the same way: wp_get_nav_menu_to_edit() queries 'any' and wp_nav_menu_update_menu_items() queries 'draft,publish', so a draft-only menu lists empty on the edit screen and its items cannot be updated or deleted there.

Steps to reproduce

$menu_id = wp_create_nav_menu( 'example' );
$menu    = wp_get_nav_menu_object( $menu_id );

$item_id = wp_update_nav_menu_item(
        $menu_id,
        0,
        array(
                'menu-item-type'   => 'custom',
                'menu-item-title'  => 'Example',
                'menu-item-url'    => 'https://example.org/',
                'menu-item-status' => 'draft',
        )
);

// Returns array() — the gate short-circuits because $menu->count is 0:
$via_function = wp_get_nav_menu_items( $menu_id, array( 'post_status' => 'draft' ) );

// Returns array( $item_id ) — the underlying query does find the item:
$via_query = wp_list_pluck(
        get_posts(
                array(
                        'post_type'   => 'nav_menu_item',
                        'post_status' => 'draft',
                        'nopaging'    => true,
                        'tax_query'   => array(
                                array(
                                        'taxonomy' => 'nav_menu',
                                        'field'    => 'term_taxonomy_id',
                                        'terms'    => $menu->term_taxonomy_id,
                                ),
                        ),
                )
        ),
        'ID'
);

Root cause

The gate was introduced in [53010] (556492a) for #55372, which replaced get_objects_in_term() + $args['include'] with a tax_query to save one query. The previous ! empty( $items ) check tested whether any objects were attached to the term at all — it was status-agnostic and reflected actual attachments. The replacement $menu->count > 0 tests the published count only and can additionally be stale, so the gate now fires in cases the old check never hit.

Fix

Remove the short-circuit and always run get_posts( $args ) — restoring the pre-[53010] approach of letting the query, not the term count, decide whether matching items exist. get_posts() already returns array() for a genuinely empty menu.

A narrower alternative — keeping the gate only for the default post_status === 'publish' query — was considered and rejected: deferred term counting and stale WP_Term snapshots both leave count = 0 while published items exist, so a publish-only gate would still return a wrong array() in precisely the cases this ticket covers.

Performance impact of removing the gate

• Warm caches, and sites with a persistent object cache: zero additional queries after a one-time cache miss per menu — the query result, including the empty result, is cached in the post-queries group. (That result cache did not yet exist when the gate was added in 6.0.)
• A site with no object cache: one additional indexed SELECT per empty rendered menu per request — it joins term_relationships and filters on term_taxonomy_id plus the type_status_date index, returning 0 rows.
• Non-empty menus: identical — the gate already passed through to the same query.

Testing instructions

Run the new regression tests, which fail before the change and pass after:

phpunit --filter Tests_Post_Nav_Menu

Or reproduce manually with the snippet under "Steps to reproduce": before the change $via_function is empty while $via_query is not; after the change both return the same item.

Tests

Adds 8 regression cases to Tests_Post_Nav_Menu, each tagged @ticket 66102:

Each of the 8 fails with the src/ change reverted and passes with it applied.

Locally (single site, PHP 8.2 / MySQL 8.0) the following all pass with the change applied: --group menu (113 tests), the customize suite (119), the REST menus controllers (79), and --group ajax (190, 1 pre-existing skip). PHPCS is clean on both changed files.

AI disclosure

AI assistance was used in preparing this patch, and is disclosed per the WordPress AI guidelines.

🤖 Generated with Claude Code