admin_menu │ action-hook │ WP 1.5.0

Allows changing admin menu items.

This hook is used to add submenus and top-level menu items to the admin menu structure with add_menu_page(), add_submenu_page(), and their derived functions.

This hook cannot be invoked on admin_init, because admin_init fires after admin_menu.

The hook runs after the basic admin menu structure has been created.

After this hook, all data in the global $menu and $submenu variables is processed further:

User capability to access each menu item is checked; see current_user_can(). If the user lacks access, the menu item is removed. The capability to check is stored at index 1 of the menu item: $data[1].
Menu sorting must first be enabled with add_filter( 'custom_menu_order', '__return_true' );. Then specify the required order with add_filter( 'menu_order', 'my_menu_order' ). See an example here.
CSS classes are added to menu items.
Access to the admin page is checked. At the end of menu creation, user_can_access_admin_page() verifies access to the current admin page using the current menu data. If access is denied, WordPress stops with this error:
```
wp_die( __( 'Sorry, you are not allowed to access this page.' ), 403 );
```

Usage

add_action( 'admin_menu', 'wp_kama_admin_menu_action' );

/**
 * Function for `admin_menu` action-hook.
 * 
 * @param string $context Empty context.
 *
 * @return void
 */
function wp_kama_admin_menu_action( $context ){

	// action...
}

$context(string): An empty string.

Examples

#1 Structure of the global $menu and $submenu variables

global $menu:

global $submenu:

#2 Change menu item names and add separators

Suppose we want to change the default admin menu item names. For example, we need separators between some items and want to rename Appearance to Themes and Plugins to Site Plugins.

Create a file (class) containing the following code:

<?php

final class Change_Admin_Menu {

	public static function init(): void {
		add_action( 'admin_menu', [ __CLASS__, 'change' ] );
	}

	public static function change() {
		global $menu;

		self::add_separator( 9 );
		self::add_separator( 70 );

		foreach( $menu as & $item ){
			// Rename Appearance to Theme
			if( 'themes.php' === $item[2] ){
				$item[0] = __( 'Theme', 'km' );
			}

			// Rename Plugins
			if( 'plugins.php' === $item[2] ){
				$item[0] = __( 'Site Plugins', 'km' );
			}
		}
		unset( $item );
	}

	/**
	 * Adds a separator to the admin menu.
	 * If the specified index already exists, increments it by one
	 * so existing menu items are not overwritten.
	 *
	 * @param int $position Index at which to add the separator.
	 *
	 * @author kama
	 * @ver 1.0
	 */
	protected static function add_separator( int $position ): void {
		global $menu;

		static $index;
		$index || ( $index = 1 );

		foreach( $menu as $mindex => $section ){

			if( $mindex >= $position ){

				while( isset( $menu[ $position ] ) ){
					++$position;
				}

				$menu[ $position ] = [
					'',
					'read',
					"separator-my{$index}",
					'',
					'wp-menu-separator'
				];

				$index++;

				break;
			}
		}

		ksort( $menu );
	}
}

Include the created file in functions.php and initialize the class:

require_once __DIR__ . '/rel/path/to/Change_Admin_Menu.php';
Change_Admin_Menu::init();

Changelog

Since 1.5.0

Introduced.

Where the hook is called

In file: /wp-admin/includes/menu.php

_network_admin_menu

admin_menu

admin_page_access_denied

wp-admin/includes/menu.php 168

do_action( 'admin_menu', '' );

Where the hook is used in WordPress

wp-admin/includes/class-custom-background.php 55

add_action( 'admin_menu', array( $this, 'init' ) );

wp-admin/includes/class-custom-image-header.php 62

add_action( 'admin_menu', array( $this, 'init' ) );

wp-admin/menu.php 269

add_action( 'admin_menu', '_add_themes_utility_last', 101 );

wp-admin/menu.php 331

add_action( 'admin_menu', '_add_plugin_file_editor_to_tools', 101 );

wp-includes/default-filters.php 592

add_action( 'admin_menu', '_add_post_type_submenus' );

wp-includes/theme.php 3117

remove_action( 'admin_menu', array( $GLOBALS['custom_image_header'], 'init' ) );

wp-includes/theme.php 3130

remove_action( 'admin_menu', array( $GLOBALS['custom_background'], 'init' ) );