add_submenu_page( string $parent_slug, string $page_title, string $menu_title, string $capability, string $menu_slug, callable $callback = '', int|float $position = null ): string|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

$parent_slugstring

The slug name for the parent menu (or the file name of a standard WordPress admin page).

$page_titlestring

The text to be displayed in the title tags of the page when the menu is selected.

$menu_titlestring

The text to be used for the menu.

$capabilitystring

The capability required for this menu to be displayed to the user.

$menu_slugstring

The slug name to refer to this menu by. Should be unique for this menu and only include lowercase alphanumeric, dashes, and underscores characters to be compatible with sanitize_key().

$callbackcallableoptional

The function to be called to output the content for this page.Default: ''

$positionint|floatoptional

The position in the menu order this item should appear.Default: null

Return value

string|false

The resulting page's hook_suffix, or false if the user does not have the capability required.

Performance profile

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

Light

Touches nothing outside its own arguments.

Scaling

Scales with input

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

Instructions

31–129

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

Plugin surface

None

Nothing here hands control to plugin code.

Called by

14

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

What it touches

• hookthird-party callbacksdo_action()one call below add_submenu_page()

Further down the call graph this can also reach query, 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 · 25 distinct outcomes

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

Uses · 7

• plugin_basename()Gets the basename of a plugin.
• current_user_can()Returns whether the current user has the specified capability.
• _doing_it_wrong()Marks something as being incorrectly called.
• __()Retrieves the translation of $text.
• absint()Converts a value to non-negative integer.
• get_plugin_page_hookname()Gets the hook name for the administrative page of a plugin.
• add_action()Adds a callback function to an action hook.

Used by · 14

• _add_plugin_file_editor_to_tools()Adds the 'Plugin File Editor' menu item after the 'Themes File Editor' in Tools for block themes.
• _add_post_type_submenus()Adds submenus for post types.
• _add_themes_utility_last()Adds the 'Theme File Editor' menu item to the bottom of the Appearance (non-block themes) or Tools (block themes) menu.
• add_comments_page()Adds a submenu page to the Comments main menu.
• add_dashboard_page()Adds a submenu page to the Dashboard main menu.
• add_links_page()Adds a submenu page to the Links main menu.
• add_management_page()Adds a submenu page to the Tools main menu.
• add_media_page()Adds a submenu page to the Media main menu.
• add_options_page()Adds a submenu page to the Settings main menu.
• add_pages_page()Adds a submenu page to the Pages main menu.
• add_plugins_page()Adds a submenu page to the Plugins main menu.
• add_posts_page()Adds a submenu page to the Posts main menu.

Source code

View on Trac ↗View on GitHub ↗

1473function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {1474	global $submenu, $menu, $_wp_real_parent_file, $_wp_submenu_nopriv,1475		$_registered_pages, $_parent_pages;1476 1477	$menu_slug   = plugin_basename( $menu_slug );1478	$parent_slug = plugin_basename( $parent_slug );1479 1480	if ( isset( $_wp_real_parent_file[ $parent_slug ] ) ) {1481		$parent_slug = $_wp_real_parent_file[ $parent_slug ];1482	}1483 1484	if ( ! current_user_can( $capability ) ) {1485		$_wp_submenu_nopriv[ $parent_slug ][ $menu_slug ] = true;1486		return false;1487	}1488 1489	/*1490	 * If the parent doesn't already have a submenu, add a link to the parent1491	 * as the first item in the submenu. If the submenu file is the same as the1492	 * parent file someone is trying to link back to the parent manually. In1493	 * this case, don't automatically add a link back to avoid duplication.1494	 */1495	if ( ! isset( $submenu[ $parent_slug ] ) && $menu_slug !== $parent_slug ) {1496		foreach ( (array) $menu as $parent_menu ) {1497			if ( $parent_menu[2] === $parent_slug && current_user_can( $parent_menu[1] ) ) {1498				$submenu[ $parent_slug ][] = array_slice( $parent_menu, 0, 4 );1499			}1500		}1501	}1502 1503	$new_sub_menu = array( $menu_title, $capability, $menu_slug, $page_title );1504 1505	if ( null !== $position && ! is_numeric( $position ) ) {1506		_doing_it_wrong(1507			__FUNCTION__,1508			sprintf(1509				/* translators: %s: add_submenu_page() */1510				__( 'The seventh parameter passed to %s should be numeric representing menu position.' ),1511				'<code>add_submenu_page()</code>'1512			),1513			'5.3.0'1514		);1515		$position = null;1516	}1517 1518	if (1519		null === $position ||1520		( ! isset( $submenu[ $parent_slug ] ) || $position >= count( $submenu[ $parent_slug ] ) )1521	) {1522		$submenu[ $parent_slug ][] = $new_sub_menu;1523	} else {1524		// Test for a negative position.1525		$position = max( $position, 0 );1526		if ( 0 === $position ) {1527			// For negative or `0` positions, prepend the submenu.1528			array_unshift( $submenu[ $parent_slug ], $new_sub_menu );1529		} else {1530			$position = absint( $position );1531			// Grab all of the items before the insertion point.1532			$before_items = array_slice( $submenu[ $parent_slug ], 0, $position, true );1533			// Grab all of the items after the insertion point.1534			$after_items = array_slice( $submenu[ $parent_slug ], $position, null, true );1535			// Add the new item.1536			$before_items[] = $new_sub_menu;1537			// Merge the items.1538			$submenu[ $parent_slug ] = array_merge( $before_items, $after_items );1539		}1540	}1541 1542	// Sort the parent array.1543	ksort( $submenu[ $parent_slug ] );1544 1545	$hookname = get_plugin_page_hookname( $menu_slug, $parent_slug );1546	if ( ! empty( $callback ) && ! empty( $hookname ) ) {1547		add_action( $hookname, $callback );1548	}1549 1550	$_registered_pages[ $hookname ] = true;1551 1552	/*

Changelog

Introduced in 1.5.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 6.8.8 tag, from src/wp-admin/includes/plugin.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.