--- a/wp/wp-admin/includes/plugin.php Wed Sep 21 18:19:35 2022 +0200
+++ b/wp/wp-admin/includes/plugin.php Tue Sep 27 16:37:53 2022 +0200
@@ -54,17 +54,19 @@
* Plugin data. Values will be empty if not supplied by the plugin.
*
* @type string $Name Name of the plugin. Should be unique.
- * @type string $Title Title of the plugin and link to the plugin's site (if set).
+ * @type string $PluginURI Plugin URI.
+ * @type string $Version Plugin version.
* @type string $Description Plugin description.
- * @type string $Author Author's name.
- * @type string $AuthorURI Author's website address (if set).
- * @type string $Version Plugin version.
+ * @type string $Author Plugin author's name.
+ * @type string $AuthorURI Plugin author's website address (if set).
* @type string $TextDomain Plugin textdomain.
- * @type string $DomainPath Plugins relative directory path to .mo files.
+ * @type string $DomainPath Plugin's relative directory path to .mo files.
* @type bool $Network Whether the plugin can only be activated network-wide.
* @type string $RequiresWP Minimum required version of WordPress.
* @type string $RequiresPHP Minimum required version of PHP.
* @type string $UpdateURI ID of the plugin for update purposes, should be a URI.
+ * @type string $Title Title of the plugin and link to the plugin's site (if set).
+ * @type string $AuthorName Plugin author's name.
* }
*/
function get_plugin_data( $plugin_file, $markup = true, $translate = true ) {
@@ -129,19 +131,8 @@
* @param bool $markup Optional. If the returned data should have HTML markup applied.
* Default true.
* @param bool $translate Optional. If the returned data should be translated. Default true.
- * @return array {
- * Plugin data. Values will be empty if not supplied by the plugin.
- *
- * @type string $Name Name of the plugin. Should be unique.
- * @type string $Title Title of the plugin and link to the plugin's site (if set).
- * @type string $Description Plugin description.
- * @type string $Author Author's name.
- * @type string $AuthorURI Author's website address (if set).
- * @type string $Version Plugin version.
- * @type string $TextDomain Plugin textdomain.
- * @type string $DomainPath Plugins relative directory path to .mo files.
- * @type bool $Network Whether the plugin can only be activated network-wide.
- * }
+ * @return array Plugin data. Values will be empty if not supplied by the plugin.
+ * See get_plugin_data() for the list of possible values.
*/
function _get_plugin_data_markup_translate( $plugin_file, $plugin_data, $markup = true, $translate = true ) {
@@ -164,8 +155,10 @@
}
if ( $textdomain ) {
foreach ( array( 'Name', 'PluginURI', 'Description', 'Author', 'AuthorURI', 'Version' ) as $field ) {
- // phpcs:ignore WordPress.WP.I18n.LowLevelTranslationFunction,WordPress.WP.I18n.NonSingularStringLiteralText,WordPress.WP.I18n.NonSingularStringLiteralDomain
- $plugin_data[ $field ] = translate( $plugin_data[ $field ], $textdomain );
+ if ( ! empty( $plugin_data[ $field ] ) ) {
+ // phpcs:ignore WordPress.WP.I18n.LowLevelTranslationFunction,WordPress.WP.I18n.NonSingularStringLiteralText,WordPress.WP.I18n.NonSingularStringLiteralDomain
+ $plugin_data[ $field ] = translate( $plugin_data[ $field ], $textdomain );
+ }
}
}
}
@@ -224,7 +217,7 @@
}
/**
- * Get a list of a plugin's files.
+ * Gets a list of a plugin's files.
*
* @since 2.8.0
*
@@ -259,7 +252,7 @@
}
/**
- * Check the plugins directory and retrieve all plugin files with plugin data.
+ * Checks the plugins directory and retrieve all plugin files with plugin data.
*
* WordPress only supports plugin files in the base plugins directory
* (wp-content/plugins) and in one directory above the plugins directory
@@ -359,7 +352,7 @@
}
/**
- * Check the mu-plugins directory and retrieve all mu-plugin files with any plugin data.
+ * Checks the mu-plugins directory and retrieve all mu-plugin files with any plugin data.
*
* WordPress only includes mu-plugin files in the base mu-plugins directory (wp-content/mu-plugins).
*
@@ -418,7 +411,7 @@
}
/**
- * Callback to sort array by a 'Name' key.
+ * Declares a callback to sort array by a 'Name' key.
*
* @since 3.1.0
*
@@ -433,7 +426,7 @@
}
/**
- * Check the wp-content directory and retrieve all drop-ins with any plugin data.
+ * Checks the wp-content directory and retrieve all drop-ins with any plugin data.
*
* @since 3.0.0
* @return array[] Array of arrays of dropin plugin data, keyed by plugin file name. See `get_plugin_data()`.
@@ -737,7 +730,7 @@
}
/**
- * Deactivate a single plugin or multiple plugins.
+ * Deactivates a single plugin or multiple plugins.
*
* The deactivation hook is disabled by the plugin upgrader by using the $silent
* parameter.
@@ -845,7 +838,7 @@
}
/**
- * Activate multiple plugins.
+ * Activates multiple plugins.
*
* When WP_Error is returned, it does not mean that one of the plugins had
* errors. It means that one or more of the plugin file paths were invalid.
@@ -885,7 +878,7 @@
}
/**
- * Remove directory and files of a plugin for a list of plugins.
+ * Removes directory and files of a plugin for a list of plugins.
*
* @since 2.6.0
*
@@ -1050,7 +1043,7 @@
}
/**
- * Validate active plugins
+ * Validates active plugins.
*
* Validate all active plugins, deactivates invalid and
* returns an array of deactivated ones.
@@ -1089,7 +1082,7 @@
}
/**
- * Validate the plugin path.
+ * Validates the plugin path.
*
* Checks that the main plugin file exists and is a valid plugin. See validate_file().
*
@@ -1191,7 +1184,7 @@
}
/**
- * Whether the plugin can be uninstalled.
+ * Determines whether the plugin can be uninstalled.
*
* @since 2.7.0
*
@@ -1210,7 +1203,7 @@
}
/**
- * Uninstall a single plugin.
+ * Uninstalls a single plugin.
*
* Calls the uninstall hook, if it is available.
*
@@ -1278,7 +1271,7 @@
//
/**
- * Add a top-level menu page.
+ * Adds a top-level menu page.
*
* This function takes a capability which will be used to determine whether
* or not a page is included in the menu.
@@ -1293,23 +1286,23 @@
* @global array $_registered_pages
* @global array $_parent_pages
*
- * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected.
- * @param string $menu_title The text to be used for the menu.
- * @param string $capability The capability required for this menu to be displayed to the user.
- * @param string $menu_slug 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().
- * @param callable $function The function to be called to output the content for this page.
- * @param string $icon_url 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.
- * @param int $position The position in the menu order this item should appear.
+ * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected.
+ * @param string $menu_title The text to be used for the menu.
+ * @param string $capability The capability required for this menu to be displayed to the user.
+ * @param string $menu_slug 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().
+ * @param callable $callback Optional. The function to be called to output the content for this page.
+ * @param string $icon_url Optional. 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.
+ * @param int|float $position Optional. The position in the menu order this item should appear.
* @return string The resulting page's hook_suffix.
*/
-function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $icon_url = '', $position = null ) {
+function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $icon_url = '', $position = null ) {
global $menu, $admin_page_hooks, $_registered_pages, $_parent_pages;
$menu_slug = plugin_basename( $menu_slug );
@@ -1318,8 +1311,8 @@
$hookname = get_plugin_page_hookname( $menu_slug, '' );
- if ( ! empty( $function ) && ! empty( $hookname ) && current_user_can( $capability ) ) {
- add_action( $hookname, $function );
+ if ( ! empty( $callback ) && ! empty( $hookname ) && current_user_can( $capability ) ) {
+ add_action( $hookname, $callback );
}
if ( empty( $icon_url ) ) {
@@ -1332,12 +1325,35 @@
$new_menu = array( $menu_title, $capability, $menu_slug, $page_title, 'menu-top ' . $icon_class . $hookname, $hookname, $icon_url );
- if ( null === $position ) {
+ if ( null !== $position && ! is_numeric( $position ) ) {
+ _doing_it_wrong(
+ __FUNCTION__,
+ sprintf(
+ /* translators: %s: add_menu_page() */
+ __( 'The seventh parameter passed to %s should be numeric representing menu position.' ),
+ '<code>add_menu_page()</code>'
+ ),
+ '6.0.0'
+ );
+ $position = null;
+ }
+
+ if ( null === $position || ! is_numeric( $position ) ) {
$menu[] = $new_menu;
- } elseif ( isset( $menu[ "$position" ] ) ) {
- $position = $position + substr( base_convert( md5( $menu_slug . $menu_title ), 16, 10 ), -5 ) * 0.00001;
- $menu[ "$position" ] = $new_menu;
+ } elseif ( isset( $menu[ (string) $position ] ) ) {
+ $collision_avoider = base_convert( substr( md5( $menu_slug . $menu_title ), -4 ), 16, 10 ) * 0.00001;
+ $position = (string) ( $position + $collision_avoider );
+ $menu[ $position ] = $new_menu;
} else {
+ /*
+ * Cast menu position to a string.
+ *
+ * This allows for floats to be passed as the position. PHP will normally cast a float to an
+ * integer value, this ensures the float retains its mantissa (positive fractional part).
+ *
+ * A string containing an integer value, eg "10", is treated as a numeric index.
+ */
+ $position = (string) $position;
$menu[ $position ] = $new_menu;
}
@@ -1350,7 +1366,7 @@
}
/**
- * Add a submenu page.
+ * Adds a submenu page.
*
* This function takes a capability which will be used to determine whether
* or not a page is included in the menu.
@@ -1368,20 +1384,20 @@
* @global array $_registered_pages
* @global array $_parent_pages
*
- * @param string $parent_slug The slug name for the parent menu (or the file name of a standard
- * WordPress admin page).
- * @param string $page_title The text to be displayed in the title tags of the page when the menu
- * is selected.
- * @param string $menu_title The text to be used for the menu.
- * @param string $capability The capability required for this menu to be displayed to the user.
- * @param string $menu_slug 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().
- * @param callable $function The function to be called to output the content for this page.
- * @param int $position The position in the menu order this item should appear.
+ * @param string $parent_slug The slug name for the parent menu (or the file name of a standard
+ * WordPress admin page).
+ * @param string $page_title The text to be displayed in the title tags of the page when the menu
+ * is selected.
+ * @param string $menu_title The text to be used for the menu.
+ * @param string $capability The capability required for this menu to be displayed to the user.
+ * @param string $menu_slug 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().
+ * @param callable $callback Optional. The function to be called to output the content for this page.
+ * @param int|float $position Optional. The position in the menu order this item should appear.
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
*/
-function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
+function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
global $submenu, $menu, $_wp_real_parent_file, $_wp_submenu_nopriv,
$_registered_pages, $_parent_pages;
@@ -1412,49 +1428,49 @@
}
$new_sub_menu = array( $menu_title, $capability, $menu_slug, $page_title );
- if ( ! is_int( $position ) ) {
- if ( null !== $position ) {
- _doing_it_wrong(
- __FUNCTION__,
- sprintf(
- /* translators: %s: add_submenu_page() */
- __( 'The seventh parameter passed to %s should be an integer representing menu position.' ),
- '<code>add_submenu_page()</code>'
- ),
- '5.3.0'
- );
- }
+ if ( null !== $position && ! is_numeric( $position ) ) {
+ _doing_it_wrong(
+ __FUNCTION__,
+ sprintf(
+ /* translators: %s: add_submenu_page() */
+ __( 'The seventh parameter passed to %s should be numeric representing menu position.' ),
+ '<code>add_submenu_page()</code>'
+ ),
+ '5.3.0'
+ );
+ $position = null;
+ }
+
+ if (
+ null === $position ||
+ ( ! isset( $submenu[ $parent_slug ] ) || $position >= count( $submenu[ $parent_slug ] ) )
+ ) {
$submenu[ $parent_slug ][] = $new_sub_menu;
} else {
- // Append the submenu if the parent item is not present in the submenu,
- // or if position is equal or higher than the number of items in the array.
- if ( ! isset( $submenu[ $parent_slug ] ) || $position >= count( $submenu[ $parent_slug ] ) ) {
- $submenu[ $parent_slug ][] = $new_sub_menu;
+ // Test for a negative position.
+ $position = max( $position, 0 );
+ if ( 0 === $position ) {
+ // For negative or `0` positions, prepend the submenu.
+ array_unshift( $submenu[ $parent_slug ], $new_sub_menu );
} else {
- // Test for a negative position.
- $position = max( $position, 0 );
- if ( 0 === $position ) {
- // For negative or `0` positions, prepend the submenu.
- array_unshift( $submenu[ $parent_slug ], $new_sub_menu );
- } else {
- // Grab all of the items before the insertion point.
- $before_items = array_slice( $submenu[ $parent_slug ], 0, $position, true );
- // Grab all of the items after the insertion point.
- $after_items = array_slice( $submenu[ $parent_slug ], $position, null, true );
- // Add the new item.
- $before_items[] = $new_sub_menu;
- // Merge the items.
- $submenu[ $parent_slug ] = array_merge( $before_items, $after_items );
- }
+ // Grab all of the items before the insertion point.
+ $before_items = array_slice( $submenu[ $parent_slug ], 0, $position, true );
+ // Grab all of the items after the insertion point.
+ $after_items = array_slice( $submenu[ $parent_slug ], $position, null, true );
+ // Add the new item.
+ $before_items[] = $new_sub_menu;
+ // Merge the items.
+ $submenu[ $parent_slug ] = array_merge( $before_items, $after_items );
}
}
+
// Sort the parent array.
ksort( $submenu[ $parent_slug ] );
$hookname = get_plugin_page_hookname( $menu_slug, $parent_slug );
- if ( ! empty( $function ) && ! empty( $hookname ) ) {
- add_action( $hookname, $function );
+ if ( ! empty( $callback ) && ! empty( $hookname ) ) {
+ add_action( $hookname, $callback );
}
$_registered_pages[ $hookname ] = true;
@@ -1474,7 +1490,7 @@
}
/**
- * Add submenu page to the Tools main menu.
+ * Adds a submenu page to the Tools main menu.
*
* This function takes a capability which will be used to determine whether
* or not a page is included in the menu.
@@ -1489,16 +1505,16 @@
* @param string $menu_title The text to be used for the menu.
* @param string $capability The capability required for this menu to be displayed to the user.
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $function The function to be called to output the content for this page.
- * @param int $position The position in the menu order this item should appear.
+ * @param callable $callback Optional. The function to be called to output the content for this page.
+ * @param int $position Optional. The position in the menu order this item should appear.
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
*/
-function add_management_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
- return add_submenu_page( 'tools.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+function add_management_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
+ return add_submenu_page( 'tools.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
}
/**
- * Add submenu page to the Settings main menu.
+ * Adds a submenu page to the Settings main menu.
*
* This function takes a capability which will be used to determine whether
* or not a page is included in the menu.
@@ -1513,16 +1529,16 @@
* @param string $menu_title The text to be used for the menu.
* @param string $capability The capability required for this menu to be displayed to the user.
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $function The function to be called to output the content for this page.
- * @param int $position The position in the menu order this item should appear.
+ * @param callable $callback Optional. The function to be called to output the content for this page.
+ * @param int $position Optional. The position in the menu order this item should appear.
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
*/
-function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
- return add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
+ return add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
}
/**
- * Add submenu page to the Appearance main menu.
+ * Adds a submenu page to the Appearance main menu.
*
* This function takes a capability which will be used to determine whether
* or not a page is included in the menu.
@@ -1537,16 +1553,16 @@
* @param string $menu_title The text to be used for the menu.
* @param string $capability The capability required for this menu to be displayed to the user.
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $function The function to be called to output the content for this page.
- * @param int $position The position in the menu order this item should appear.
+ * @param callable $callback Optional. The function to be called to output the content for this page.
+ * @param int $position Optional. The position in the menu order this item should appear.
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
*/
-function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
- return add_submenu_page( 'themes.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
+ return add_submenu_page( 'themes.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
}
/**
- * Add submenu page to the Plugins main menu.
+ * Adds a submenu page to the Plugins main menu.
*
* This function takes a capability which will be used to determine whether
* or not a page is included in the menu.
@@ -1561,16 +1577,16 @@
* @param string $menu_title The text to be used for the menu.
* @param string $capability The capability required for this menu to be displayed to the user.
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $function The function to be called to output the content for this page.
- * @param int $position The position in the menu order this item should appear.
+ * @param callable $callback Optional. The function to be called to output the content for this page.
+ * @param int $position Optional. The position in the menu order this item should appear.
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
*/
-function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
- return add_submenu_page( 'plugins.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
+ return add_submenu_page( 'plugins.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
}
/**
- * Add submenu page to the Users/Profile main menu.
+ * Adds a submenu page to the Users/Profile main menu.
*
* This function takes a capability which will be used to determine whether
* or not a page is included in the menu.
@@ -1585,21 +1601,21 @@
* @param string $menu_title The text to be used for the menu.
* @param string $capability The capability required for this menu to be displayed to the user.
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $function The function to be called to output the content for this page.
- * @param int $position The position in the menu order this item should appear.
+ * @param callable $callback Optional. The function to be called to output the content for this page.
+ * @param int $position Optional. The position in the menu order this item should appear.
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
*/
-function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
+function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
if ( current_user_can( 'edit_users' ) ) {
$parent = 'users.php';
} else {
$parent = 'profile.php';
}
- return add_submenu_page( $parent, $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+ return add_submenu_page( $parent, $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
}
/**
- * Add submenu page to the Dashboard main menu.
+ * Adds a submenu page to the Dashboard main menu.
*
* This function takes a capability which will be used to determine whether
* or not a page is included in the menu.
@@ -1614,16 +1630,16 @@
* @param string $menu_title The text to be used for the menu.
* @param string $capability The capability required for this menu to be displayed to the user.
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $function The function to be called to output the content for this page.
- * @param int $position The position in the menu order this item should appear.
+ * @param callable $callback Optional. The function to be called to output the content for this page.
+ * @param int $position Optional. The position in the menu order this item should appear.
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
*/
-function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
- return add_submenu_page( 'index.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
+ return add_submenu_page( 'index.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
}
/**
- * Add submenu page to the Posts main menu.
+ * Adds a submenu page to the Posts main menu.
*
* This function takes a capability which will be used to determine whether
* or not a page is included in the menu.
@@ -1638,16 +1654,16 @@
* @param string $menu_title The text to be used for the menu.
* @param string $capability The capability required for this menu to be displayed to the user.
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $function The function to be called to output the content for this page.
- * @param int $position The position in the menu order this item should appear.
+ * @param callable $callback Optional. The function to be called to output the content for this page.
+ * @param int $position Optional. The position in the menu order this item should appear.
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
*/
-function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
- return add_submenu_page( 'edit.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
+ return add_submenu_page( 'edit.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
}
/**
- * Add submenu page to the Media main menu.
+ * Adds a submenu page to the Media main menu.
*
* This function takes a capability which will be used to determine whether
* or not a page is included in the menu.
@@ -1662,16 +1678,16 @@
* @param string $menu_title The text to be used for the menu.
* @param string $capability The capability required for this menu to be displayed to the user.
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $function The function to be called to output the content for this page.
- * @param int $position The position in the menu order this item should appear.
+ * @param callable $callback Optional. The function to be called to output the content for this page.
+ * @param int $position Optional. The position in the menu order this item should appear.
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
*/
-function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
- return add_submenu_page( 'upload.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
+ return add_submenu_page( 'upload.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
}
/**
- * Add submenu page to the Links main menu.
+ * Adds a submenu page to the Links main menu.
*
* This function takes a capability which will be used to determine whether
* or not a page is included in the menu.
@@ -1686,16 +1702,16 @@
* @param string $menu_title The text to be used for the menu.
* @param string $capability The capability required for this menu to be displayed to the user.
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $function The function to be called to output the content for this page.
- * @param int $position The position in the menu order this item should appear.
+ * @param callable $callback Optional. The function to be called to output the content for this page.
+ * @param int $position Optional. The position in the menu order this item should appear.
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
*/
-function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
- return add_submenu_page( 'link-manager.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
+ return add_submenu_page( 'link-manager.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
}
/**
- * Add submenu page to the Pages main menu.
+ * Adds a submenu page to the Pages main menu.
*
* This function takes a capability which will be used to determine whether
* or not a page is included in the menu.
@@ -1710,16 +1726,16 @@
* @param string $menu_title The text to be used for the menu.
* @param string $capability The capability required for this menu to be displayed to the user.
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $function The function to be called to output the content for this page.
- * @param int $position The position in the menu order this item should appear.
+ * @param callable $callback Optional. The function to be called to output the content for this page.
+ * @param int $position Optional. The position in the menu order this item should appear.
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
*/
-function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
- return add_submenu_page( 'edit.php?post_type=page', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
+ return add_submenu_page( 'edit.php?post_type=page', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
}
/**
- * Add submenu page to the Comments main menu.
+ * Adds a submenu page to the Comments main menu.
*
* This function takes a capability which will be used to determine whether
* or not a page is included in the menu.
@@ -1734,16 +1750,21 @@
* @param string $menu_title The text to be used for the menu.
* @param string $capability The capability required for this menu to be displayed to the user.
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
- * @param callable $function The function to be called to output the content for this page.
- * @param int $position The position in the menu order this item should appear.
+ * @param callable $callback Optional. The function to be called to output the content for this page.
+ * @param int $position Optional. The position in the menu order this item should appear.
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
*/
-function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
- return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
+ return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
}
/**
- * Remove a top-level admin menu.
+ * Removes a top-level admin menu.
+ *
+ * Example usage:
+ *
+ * - `remove_menu_page( 'tools.php' )`
+ * - `remove_menu_page( 'plugin_menu_slug' )`
*
* @since 3.1.0
*
@@ -1766,7 +1787,13 @@
}
/**
- * Remove an admin submenu.
+ * Removes an admin submenu.
+ *
+ * Example usage:
+ *
+ * - `remove_submenu_page( 'themes.php', 'nav-menus.php' )`
+ * - `remove_submenu_page( 'tools.php', 'plugin_submenu_slug' )`
+ * - `remove_submenu_page( 'plugin_menu_slug', 'plugin_submenu_slug' )`
*
* @since 3.1.0
*
@@ -1794,7 +1821,7 @@
}
/**
- * Get the URL to access a particular menu page based on the slug it was registered with.
+ * Gets the URL to access a particular menu page based on the slug it was registered with.
*
* If the slug hasn't been registered properly, no URL will be returned.
*
@@ -1803,10 +1830,10 @@
* @global array $_parent_pages
*
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
- * @param bool $echo Whether or not to echo the URL. Default true.
+ * @param bool $display Optional. Whether or not to display the URL. Default true.
* @return string The menu page URL.
*/
-function menu_page_url( $menu_slug, $echo = true ) {
+function menu_page_url( $menu_slug, $display = true ) {
global $_parent_pages;
if ( isset( $_parent_pages[ $menu_slug ] ) ) {
@@ -1823,7 +1850,7 @@
$url = esc_url( $url );
- if ( $echo ) {
+ if ( $display ) {
echo $url;
}
@@ -1841,27 +1868,27 @@
* @global string $parent_file
* @global array $menu
* @global array $submenu
- * @global string $pagenow
- * @global string $typenow
+ * @global string $pagenow The filename of the current screen.
+ * @global string $typenow The post type of the current screen.
* @global string $plugin_page
* @global array $_wp_real_parent_file
* @global array $_wp_menu_nopriv
* @global array $_wp_submenu_nopriv
*
- * @param string $parent The slug name for the parent menu (or the file name of a standard
- * WordPress admin page). Default empty string.
+ * @param string $parent_page Optional. The slug name for the parent menu (or the file name
+ * of a standard WordPress admin page). Default empty string.
* @return string The parent file of the current admin page.
*/
-function get_admin_page_parent( $parent = '' ) {
+function get_admin_page_parent( $parent_page = '' ) {
global $parent_file, $menu, $submenu, $pagenow, $typenow,
$plugin_page, $_wp_real_parent_file, $_wp_menu_nopriv, $_wp_submenu_nopriv;
- if ( ! empty( $parent ) && 'admin.php' !== $parent ) {
- if ( isset( $_wp_real_parent_file[ $parent ] ) ) {
- $parent = $_wp_real_parent_file[ $parent ];
+ if ( ! empty( $parent_page ) && 'admin.php' !== $parent_page ) {
+ if ( isset( $_wp_real_parent_file[ $parent_page ] ) ) {
+ $parent_page = $_wp_real_parent_file[ $parent_page ];
}
- return $parent;
+ return $parent_page;
}
if ( 'admin.php' === $pagenow && isset( $plugin_page ) ) {
@@ -1897,23 +1924,23 @@
return $parent_file;
}
- foreach ( array_keys( (array) $submenu ) as $parent ) {
- foreach ( $submenu[ $parent ] as $submenu_array ) {
- if ( isset( $_wp_real_parent_file[ $parent ] ) ) {
- $parent = $_wp_real_parent_file[ $parent ];
+ foreach ( array_keys( (array) $submenu ) as $parent_page ) {
+ foreach ( $submenu[ $parent_page ] as $submenu_array ) {
+ if ( isset( $_wp_real_parent_file[ $parent_page ] ) ) {
+ $parent_page = $_wp_real_parent_file[ $parent_page ];
}
if ( ! empty( $typenow ) && "$pagenow?post_type=$typenow" === $submenu_array[2] ) {
- $parent_file = $parent;
- return $parent;
+ $parent_file = $parent_page;
+ return $parent_page;
} elseif ( empty( $typenow ) && $pagenow === $submenu_array[2]
&& ( empty( $parent_file ) || false === strpos( $parent_file, '?' ) )
) {
- $parent_file = $parent;
- return $parent;
+ $parent_file = $parent_page;
+ return $parent_page;
} elseif ( isset( $plugin_page ) && $plugin_page === $submenu_array[2] ) {
- $parent_file = $parent;
- return $parent;
+ $parent_file = $parent_page;
+ return $parent_page;
}
}
}
@@ -1930,16 +1957,16 @@
* @since 1.5.0
*
* @global string $title
- * @global array $menu
- * @global array $submenu
- * @global string $pagenow
+ * @global array $menu
+ * @global array $submenu
+ * @global string $pagenow The filename of the current screen.
+ * @global string $typenow The post type of the current screen.
* @global string $plugin_page
- * @global string $typenow
*
* @return string The title of the current admin page.
*/
function get_admin_page_title() {
- global $title, $menu, $submenu, $pagenow, $plugin_page, $typenow;
+ global $title, $menu, $submenu, $pagenow, $typenow, $plugin_page;
if ( ! empty( $title ) ) {
return $title;
@@ -2067,7 +2094,7 @@
*
* @since 1.5.0
*
- * @global string $pagenow
+ * @global string $pagenow The filename of the current screen.
* @global array $menu
* @global array $submenu
* @global array $_wp_menu_nopriv
@@ -2242,7 +2269,7 @@
}
/**
- * Output nonce, action, and option_page fields for a settings page.
+ * Outputs nonce, action, and option_page fields for a settings page.
*
* @since 2.7.0
*
@@ -2270,7 +2297,7 @@
}
/**
- * Load a given plugin attempt to generate errors.
+ * Loads a given plugin attempt to generate errors.
*
* @since 3.0.0
* @since 4.4.0 Function was moved into the `wp-admin/includes/plugin.php` file.
@@ -2287,7 +2314,7 @@
}
/**
- * Helper function for adding content to the Privacy Policy Guide.
+ * Declares a helper function for adding content to the Privacy Policy Guide.
*
* Plugins and themes should suggest text for inclusion in the site's privacy policy.
* The suggested text should contain information about any functionality that affects user privacy,
@@ -2450,7 +2477,7 @@
*
* @since 5.2.0
*
- * @global string $pagenow
+ * @global string $pagenow The filename of the current screen.
*/
function paused_plugins_notice() {
if ( 'plugins.php' === $GLOBALS['pagenow'] ) {
@@ -2483,8 +2510,8 @@
* @since 5.8.0
* @access private
*
- * @global string $pagenow
- * @global string $wp_version
+ * @global string $pagenow The filename of the current screen.
+ * @global string $wp_version The WordPress version string.
*/
function deactivated_plugins_notice() {
if ( 'plugins.php' === $GLOBALS['pagenow'] ) {
@@ -2521,7 +2548,7 @@
foreach ( $deactivated_plugins as $plugin ) {
if ( ! empty( $plugin['version_compatible'] ) && ! empty( $plugin['version_deactivated'] ) ) {
$explanation = sprintf(
- /* translators: 1: Name of deactivated plugin, 2: Plugin version deactivated, 3: Current WP version, 4: Compatible plugin version */
+ /* translators: 1: Name of deactivated plugin, 2: Plugin version deactivated, 3: Current WP version, 4: Compatible plugin version. */
__( '%1$s %2$s was deactivated due to incompatibility with WordPress %3$s, please upgrade to %1$s %4$s or later.' ),
$plugin['plugin_name'],
$plugin['version_deactivated'],
@@ -2530,7 +2557,7 @@
);
} else {
$explanation = sprintf(
- /* translators: 1: Name of deactivated plugin, 2: Plugin version deactivated, 3: Current WP version */
+ /* translators: 1: Name of deactivated plugin, 2: Plugin version deactivated, 3: Current WP version. */
__( '%1$s %2$s was deactivated due to incompatibility with WordPress %3$s.' ),
$plugin['plugin_name'],
! empty( $plugin['version_deactivated'] ) ? $plugin['version_deactivated'] : '',
@@ -2542,7 +2569,7 @@
printf(
'<div class="notice notice-warning"><p><strong>%s</strong><br>%s</p><p><a href="%s">%s</a></p></div>',
sprintf(
- /* translators: %s: Name of deactivated plugin */
+ /* translators: %s: Name of deactivated plugin. */
__( '%s plugin deactivated during WordPress upgrade.' ),
$plugin['plugin_name']
),