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 ↗

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

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 7.0.4 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.