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

$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 page 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: ''

$icon_urlstringoptional

The URL to the icon to be used for this menu.
Pass a base64-encoded SVG using a data URI, which will be colored to match the color scheme. This should begin with 'data:image/svg+xml;base64,'.
Pass the name of a Dashicons helper class to use a font icon, e.g. 'dashicons-chart-pie'.
* Pass 'none' to leave div.wp-menu-image empty so an icon can be added via CSS.Default: ''

$positionint|floatoptional

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

Return value

string

The resulting page's hook_suffix.

Performance profile

How much work a call to add_menu_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

Trivial

Touches nothing outside its own arguments.

Scaling

Constant

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

Instructions

54–100

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

Plugin surface

None

Nothing here hands control to plugin code.

Called by

2

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

What it touches

• hookthird-party callbacksapply_filters()one call below add_menu_page()

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

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

Uses · 8

• plugin_basename()Gets the basename of a plugin.
• sanitize_title()Sanitizes a string into a slug, which can be used in URLs or HTML attributes.
• get_plugin_page_hookname()Gets the hook name for the administrative page of a plugin.
• current_user_can()Returns whether the current user has the specified capability.
• add_action()Adds a callback function to an action hook.
• set_url_scheme()Sets the scheme for a URL.
• _doing_it_wrong()Marks something as being incorrectly called.
• __()Retrieves the translation of $text.

Used by · 2

• add_object_page()Add a top-level menu page in the 'objects' section.
• add_utility_page()Add a top-level menu page in the 'utility' section.

Source code

View on Trac ↗View on GitHub ↗

1378function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $icon_url = '', $position = null ) {1379	global $menu, $admin_page_hooks, $_registered_pages, $_parent_pages;1380 1381	$menu_slug = plugin_basename( $menu_slug );1382 1383	$admin_page_hooks[ $menu_slug ] = sanitize_title( $menu_title );1384 1385	$hookname = get_plugin_page_hookname( $menu_slug, '' );1386 1387	if ( ! empty( $callback ) && ! empty( $hookname ) && current_user_can( $capability ) ) {1388		add_action( $hookname, $callback );1389	}1390 1391	if ( empty( $icon_url ) ) {1392		$icon_url   = 'dashicons-admin-generic';1393		$icon_class = 'menu-icon-generic ';1394	} else {1395		$icon_url   = set_url_scheme( $icon_url );1396		$icon_class = '';1397	}1398 1399	$new_menu = array( $menu_title, $capability, $menu_slug, $page_title, 'menu-top ' . $icon_class . $hookname, $hookname, $icon_url );1400 1401	if ( null !== $position && ! is_numeric( $position ) ) {1402		_doing_it_wrong(1403			__FUNCTION__,1404			sprintf(1405				/* translators: %s: add_menu_page() */1406				__( 'The seventh parameter passed to %s should be numeric representing menu position.' ),1407				'<code>add_menu_page()</code>'1408			),1409			'6.0.0'1410		);1411		$position = null;1412	}1413 1414	if ( null === $position || ! is_numeric( $position ) ) {1415		$menu[] = $new_menu;1416	} elseif ( isset( $menu[ (string) $position ] ) ) {1417		$collision_avoider = base_convert( substr( md5( $menu_slug . $menu_title ), -4 ), 16, 10 ) * 0.00001;1418		$position          = (string) ( $position + $collision_avoider );1419		$menu[ $position ] = $new_menu;1420	} else {1421		/*1422		 * Cast menu position to a string.1423		 *1424		 * This allows for floats to be passed as the position. PHP will normally cast a float to an1425		 * integer value, this ensures the float retains its mantissa (positive fractional part).1426		 *1427		 * A string containing an integer value, eg "10", is treated as a numeric index.1428		 */1429		$position          = (string) $position;1430		$menu[ $position ] = $new_menu;1431	}1432 1433	$_registered_pages[ $hookname ] = true;1434 1435	// No parent as top level.1436	$_parent_pages[ $menu_slug ] = false;1437 1438	return $hookname;1439}

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.