Allow plugins to short-circuit wp_nav_menu, good for performance

[kasparsd]

We already have short-circuit filters for ​widgets, ​options, ​links that all can be used for retrieving items from non-persistent data store. It would make a lot of sense if this feature was also available to wp_nav_menu which is particularly DB heavy.

My suggestion is to add pre_wp_nav_menu right after wp_nav_menu_args, like so:

	$args = wp_parse_args( $args, $defaults );
	$args = apply_filters( 'wp_nav_menu_args', $args );
	$args = (object) $args;

	// Allow plugins to short-circuit menu output
	$nav_menu = apply_filters( 'pre_wp_nav_menu', '', $args );

	if ( ! empty( $nav_menu ) && $args->echo )
		echo $nav_menu;
	elseif ( ! empty( $nav_menu ) )
		return $nav_menu;

	// Get the nav menu based on the requested menu
	$menu = wp_get_nav_menu_object( $args->menu );

[kasparsd]

Patch

[kasparsd]

Here is a link to ​wp_nav_menu.

[kasparsd]

Wrote a blog post explaining my reasoning behind this filter ​http://konstruktors.com/blog/wordpress/4594-filter-pre-wp-nav-menu/

[Rarst]

+1, must have - menus are slooow.

For those who need it right now, there is a roundabout way to make this happen by forcing core to see no menus at all, which triggers custom callback. See implementation in my Fragment Cache plugin ​https://bitbucket.org/Rarst/fragment-cache/src/tip/php/class-menu-cache.php

[nacin]

Sounds good to me. Note that we ​always require braces around if statements now.

Rarst, anything we can do to speed up menus? I have not profiled this area of core in quite a while.

[Rarst]

Rarst, anything we can do to speed up menus?I have not profiled this area of core in quite a while.

For the scope of my plugin I just carved whole menu out into async generation, so hadn't paid much attention to what goes on inside.

If there is interest I will poke through it some time.

[kasparsd]

I just noticed that there is a bug in the patch -- it will continue executing the function even after echoing the filtered output. There should be a return after echo. I'll make a new patch that uses braces as suggested by @nacin.

[kasparsd]

Use WP coding standards, return on echo.

[nacin]

A few other things I'd suggest:

• Returning false or '' should cause the function to short-circuit. Only returning null should allow execution to continue. (While I prefer this, core has historically reversed false and null. Either works.)
• The filter will ​need documentation.

[kasparsd]

Added documentation and used strict comparison for the short-circuit.

[kasparsd]

Replying to nacin:

A few other things I'd suggest:

Thanks for the suggestions, @nacin!

I have added a modified patch. Not sure how to describe the default filter argument/value null in the PHPDoc.

[DrewAPicture]

hook docs tweaks

[DrewAPicture]

Replying to kasparsd:

Replying to nacin:

A few other things I'd suggest:

Thanks for the suggestions, @nacin!

I have added a modified patch. Not sure how to describe the default filter argument/value null in the PHPDoc.

For the null, I usually try to just describe what the value basically is. And you can just use a docs-specific variable, maybe something like $output, e.g.:

* @param string|null $output Nav menu output to short-circuit with. Default null.

I've made that adjustment and others to the hook doc in 23627.diff​.

Notably, in the description I avoided describing why it's filterable, rather describing what's filterable. Typically we'll use a long description to outline the *why* or reasoning if it's unclear in the short description -- which I added in the patch.

I also moved the @see tag out of an in-line parameter description.

[kasparsd]

Replying to DrewAPicture:

Looks great, Drew! Thank you very much.

[Rarst]

Nitpicking on patch - why check for null twice? Also yoda condition.

if ( null !== $nav_menu  ) {

	if ( $args->echo ) {
		echo $nav_menu;
		return;
	}

	return $nav_menu;
}

[kasparsd]

Replying to Rarst:

Nitpicking on patch - why check for null twice? Also yoda condition.

I personally find the single level indentation more readable. Agreed about Yoda.

[nacin]

I agree with Rarst, as does helen (see IRC). She's handling commit.

[helen]

In 27386:

Add the ability to short-circuit wp_nav_menu() via the pre_wp_nav_menu hook. props kasparsd, DrewAPicture, Rarst. fixes #23627.