wp_page_menu( array|string $args = array() ): void|string

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

$argsarray|stringoptional

Array or string of arguments to generate a page menu. See wp_list_pages() for additional arguments.Default: array()

• $sort_columnstringdefault: 'menu_order, post_title'

  How to sort the list of pages. Accepts post column names.

• $menu_idstringdefault: is empty string

  ID for the div containing the page list.

• $menu_classstringdefault: 'menu'

  Class to use for the element containing the page list.

• $containerstringdefault: 'div'

  Element to use for the element containing the page list.

• $echobooldefault: true

  Whether to echo the list or return it. Accepts true (echo) or false (return).

• $show_homeint|bool|string

  Whether to display the link to the home page. Can just enter the text you'd like shown for the home link. 1|true defaults to 'Home'.

• $link_beforestringdefault: empty

  The HTML or text to prepend to $show_home text.

• $link_afterstringdefault: empty

  The HTML or text to append to $show_home text.

• $beforestringdefault: is ''

  The HTML or text to prepend to the menu.

• $afterstringdefault: is ''

  The HTML or text to append to the menu.

• $item_spacingstringdefault: 'discard'

  Whether to preserve whitespace within the menu's HTML. Accepts 'preserve' or 'discard'.

• $walkerWalkerdefault: empty which results in a Walker_Page instance being used

  Walker instance to use for listing pages.

Return value

void|string

Void if 'echo' argument is true, HTML menu if 'echo' is false.

Performance profile

How much work a call to wp_page_menu() 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_pages().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

65–154

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

Plugin surface

2 hooks

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

Called by

0

Nothing in core calls this; the cost is only what you spend yourself.

What it touches

• hookthird-party callbacksapply_filters()called directly
• optionoption read or writeget_option()called directly
• cacheobject cachewp_cache_get()one call below wp_page_menu()
• serializeserialisationmaybe_unserialize()one call below wp_page_menu()
• querycontent queryget_pages()one call below wp_page_menu()

Further down the call graph this can also reach transient. That is the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 27 distinct outcomes

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

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 2

2 hooks fire while wp_page_menu() runs, in this order:

1. 1
   apply_filters( wp_page_menu_args )filterline 1465 (+39 into the body)

   Filters the arguments used to generate a page-based menu.

2. 2
   apply_filters( wp_page_menu )filterline 1540 (+114 into the body)

   Filters the HTML output of a page-based menu.

Uses · 11

• wp_parse_args()Merges user defined arguments into defaults array.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• __()Retrieves the translation of $text.
• is_front_page()Determines whether the query is for the front page of the site.
• is_paged()Determines whether the query is for a paged result and not for the first page.
• esc_url()Checks and cleans a URL.
• home_url()Retrieves the URL for the current site where the front end is accessible.
• get_option()Retrieves an option value based on an option name.
• wp_list_pages()Retrieves or displays a list of pages (or hierarchical post type items) in list (li) format.
• sanitize_text_field()Sanitizes a string from user input or from the database.
• esc_attr()Escaping for HTML attributes.

Source code

View on Trac ↗View on GitHub ↗

1426function wp_page_menu( $args = array() ) {1427	$defaults = array(1428		'sort_column'  => 'menu_order, post_title',1429		'menu_id'      => '',1430		'menu_class'   => 'menu',1431		'container'    => 'div',1432		'echo'         => true,1433		'link_before'  => '',1434		'link_after'   => '',1435		'before'       => '<ul>',1436		'after'        => '</ul>',1437		'item_spacing' => 'discard',1438		'walker'       => '',1439	);1440	$args     = wp_parse_args( $args, $defaults );1441 1442	if ( ! in_array( $args['item_spacing'], array( 'preserve', 'discard' ), true ) ) {1443		// Invalid value, fall back to default.1444		$args['item_spacing'] = $defaults['item_spacing'];1445	}1446 1447	if ( 'preserve' === $args['item_spacing'] ) {1448		$t = "\t";1449		$n = "\n";1450	} else {1451		$t = '';1452		$n = '';1453	}1454 1455	/**1456	 * Filters the arguments used to generate a page-based menu.1457	 *1458	 * @since 2.7.01459	 *1460	 * @see wp_page_menu()1461	 *1462	 * @param array $args An array of page menu arguments. See wp_page_menu()1463	 *                    for information on accepted arguments.1464	 */1465	$args = apply_filters( 'wp_page_menu_args', $args );1466 1467	$menu = '';1468 1469	$list_args = $args;1470 1471	// Show Home in the menu.1472	if ( ! empty( $args['show_home'] ) ) {1473		if ( true === $args['show_home'] || '1' === $args['show_home'] || 1 === $args['show_home'] ) {1474			$text = __( 'Home' );1475		} else {1476			$text = $args['show_home'];1477		}1478		$class = '';1479		if ( is_front_page() && ! is_paged() ) {1480			$class = 'class="current_page_item"';1481		}1482		$menu .= '<li ' . $class . '><a href="' . esc_url( home_url( '/' ) ) . '">' . $args['link_before'] . $text . $args['link_after'] . '</a></li>';1483		// If the front page is a page, add it to the exclude list.1484		if ( 'page' === get_option( 'show_on_front' ) ) {1485			if ( ! empty( $list_args['exclude'] ) ) {1486				$list_args['exclude'] .= ',';1487			} else {1488				$list_args['exclude'] = '';1489			}1490			$list_args['exclude'] .= get_option( 'page_on_front' );1491		}1492	}1493 1494	$list_args['echo']     = false;1495	$list_args['title_li'] = '';1496	$menu                 .= wp_list_pages( $list_args );1497 1498	$container = sanitize_text_field( $args['container'] );1499 1500	// Fallback in case `wp_nav_menu()` was called without a container.1501	if ( empty( $container ) ) {1502		$container = 'div';1503	}1504 1505	if ( $menu ) {

Changelog

Introduced in 2.7.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.0.4 tag, from src/wp-includes/post-template.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.