WordPress.org

Make WordPress Core

Changeset 40967


Ignore:
Timestamp:
06/30/2017 04:17:56 AM (4 years ago)
Author:
DrewAPicture
Message:

Docs: Provide best practice guidance for achieving parity between $menu_slug values supplied when adding menu and submenu pages, and later trying to compare those initial values against sanitized screen IDs derived from $menu_slug.

At the heart of the matter, the $menu_slug parameter in add_menu_page() and add_submenu_page() is not sanitized with sanitize_key(). When the screen object is later built for the admin page, the screen ID is derived from that $menu_slug value, though passed through sanitize_key(), which can produce unexpected results in comparison check.

Changing the sanitization code to provide actual parity is out of the question at this juncture, so updating the docs to describe how to avoid this edge case is the next best option.

Props GregRoss.
Fixes #35305.

Location:
trunk/src/wp-admin/includes
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/includes/plugin.php

    r39890 r40967  
    10611061 * @param string   $menu_title The text to be used for the menu.
    10621062 * @param string   $capability The capability required for this menu to be displayed to the user.
    1063  * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
     1063 * @param string   $menu_slug  The slug name to refer to this menu by. Should be unique for this menu page and only
     1064 *                             include lowercase alphanumeric, dashes, and underscores characters to be compatible
     1065 *                             with sanitize_key().
    10641066 * @param callable $function   The function to be called to output the content for this page.
    10651067 * @param string   $icon_url   The URL to the icon to be used for this menu.
     
    11271129 * @global array $_parent_pages
    11281130 *
    1129  * @param string   $parent_slug The slug name for the parent menu (or the file name of a standard WordPress admin page).
    1130  * @param string   $page_title  The text to be displayed in the title tags of the page when the menu is selected.
     1131 * @param string   $parent_slug The slug name for the parent menu (or the file name of a standard
     1132 *                              WordPress admin page).
     1133 * @param string   $page_title  The text to be displayed in the title tags of the page when the menu
     1134 *                              is selected.
    11311135 * @param string   $menu_title  The text to be used for the menu.
    11321136 * @param string   $capability  The capability required for this menu to be displayed to the user.
    1133  * @param string   $menu_slug   The slug name to refer to this menu by (should be unique for this menu).
     1137 * @param string   $menu_slug   The slug name to refer to this menu by. Should be unique for this menu
     1138 *                              and only include lowercase alphanumeric, dashes, and underscores characters
     1139 *                              to be compatible with sanitize_key().
    11341140 * @param callable $function    The function to be called to output the content for this page.
    11351141 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
  • trunk/src/wp-admin/includes/template.php

    r40823 r40967  
    893893 *                                              (such as a post type, 'link', or 'comment'). Accepts a single
    894894 *                                              screen ID, WP_Screen object, or array of screen IDs. Default
    895  *                                              is the current screen.
     895 *                                              is the current screen.  If you have used add_menu_page() or
     896 *                                              add_submenu_page() to create a new screen (and hence screen_id),
     897 *                                              make sure your menu slug conforms to the limits of sanitize_key()
     898 *                                              otherwise the 'screen' menu may not correctly render on your page.
    896899 * @param string                 $context       Optional. The context within the screen where the boxes
    897900 *                                              should display. Available contexts vary from screen to
     
    988991 *
    989992 * @staticvar bool $already_sorted
    990  * @param string|WP_Screen $screen  Screen identifier
     993 *
     994 * @param string|WP_Screen $screen  Screen identifier. If you have used add_menu_page() or
     995 *                                  add_submenu_page() to create a new screen (and hence screen_id)
     996 *                                  make sure your menu slug conforms to the limits of sanitize_key()
     997 *                                  otherwise the 'screen' menu may not correctly render on your page.
    991998 * @param string           $context box context
    992999 * @param mixed            $object  gets passed to the box callback function as first parameter
Note: See TracChangeset for help on using the changeset viewer.