WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 3 years ago

#15067 closed enhancement (maybelater)

Deprecate exiting admin menu functions and add new ones that accept an $args parameter instead

Reported by: mikeschinkel Owned by:
Milestone: Priority: normal
Severity: normal Version:
Component: Administration Keywords: has-patch
Focuses: Cc:

Description

Compared to the many other APIs that accept $args the admin menu functions (add_menu_page(), add_submenu_page(), etc.) are less accessible because of the 6 and 7 ordinal parameters are hard to remember and easy to get wrong.

Suggestion is to deprecate those functions and replace with functional equivalents that use an $args array. Since the functions are for admin menus but the names of the functions appear to be generic, we could easily name these proposed functions add_admin_menu_page() and add_admin_submenu_page().

See #12718.

Attachments (2)

15067.diff (10.0 KB) - added by markjaquith 3 years ago.
First swing. No no params added yet.
15067.2.diff (8.6 KB) - added by johnjamesjacoby 3 years ago.
Patch applies clean. I like that it doesn't trigger deprecated notices yet. Refreshed to remove unnecessary brackets per coding standard.

Download all attachments as: .zip

Change History (13)

comment:1 nacin4 years ago

Per #13937, we can probably do this without deprecating entire functions.

comment:2 scribu4 years ago

  • Component changed from Menus to Administration

comment:3 nacin3 years ago

  • Milestone Awaiting Review deleted
  • Resolution set to maybelater
  • Status changed from new to closed

No traction on this. Would need to see a patch.

All of the arguments here are required, so $args is less helpful.

comment:4 mikeschinkel3 years ago

I'd forgotten about this.

Not all arguments are required; $ment_title could default to $page_title, $capability could default to 'read' if not 'edit_posts', and $function, $icon_url, and $position are defaulted so it could easily be:

add_menu_page(array(
  'page_title'=> "My Menu Page',
  'menu_slug'=> "edit.php?foo=bar',
))

I'll work on a patch soon.

BTW, would register_menu_page() be inappropriate semantics and if so why? (I ask so I can understand when "add" is appropriate and "register" is appropriate.)

comment:5 markjaquith3 years ago

  • Milestone set to 3.2
  • Resolution maybelater deleted
  • Status changed from closed to reopened

For some of the admin header changes we're working on for the UI refresh, we need some more things to be specified when registering admin pages. Let's do this, and have the array be the exclusive way of setting those new params.

markjaquith3 years ago

First swing. No no params added yet.

comment:6 follow-up: jamescollins3 years ago

I'm thinking it would still make sense to raise a deprecated warning if an Array of args isn't passed to the functions?

That way we're encouraging themes and plugins to adopt the new args array, which has the new additional arguments available.

comment:7 westi3 years ago

I'm not a big fan of using an array for arguments when they are all required.

It actually breaks the whole point of having a named argument list.

With this change you loose all the IDE hinting you get from having named arguments.

I don't see a strong benefit from this change.

comment:8 in reply to: ↑ 6 mikeschinkel3 years ago

Replying to markjaquith:

For some of the admin header changes we're working on for the UI refresh, we need some more things to be specified when registering admin pages. Let's do this, and have the array be the exclusive way of setting those new params.

Excellent! This will be a really helpful change.

Replying to jamescollins:

I'm thinking it would still make sense to raise a deprecated warning if an Array of args isn't passed to the functions?

That way we're encouraging themes and plugins to adopt the new args array, which has the new additional arguments available.

In principle I agree but in practice so many plugins have the old approach it would make it very hard to use WP_DEBUG without throwing warnings for quite a while, assuming (m)any plugins were used. Maybe deprecate in 3.5 or later?

Replying to westi:

I'm not a big fan of using an array for arguments when they are all required.

I'm confused by your assertion; they are not all required, only a few are. Consider add_menu_page():

add_menu_page( 
  $page_title, 
  $menu_title, 
  $capability, 
  $menu_slug,  
  $function, 
  $icon_url, 
  $position 
);

The only arguments that are actually required are $page_title and $menu_slug; everything else can take a default.

It actually breaks the whole point of having a named argument list.

An argument list couples the calling code with the called code very tightly, and requires that anything new must be added to the end. This results in increasing complexity over time as people wanting to use those latter parameters must at least supply dummy values for the prior values. And an argument list requires the order to be remembered by the person writing the code, and makes for less self-documenting code because the name of the parameter is not used in the calling code.

Named argument lists are an aging paradigm used when the performance of using a stack for passing arguments was significant enough for execution speed compared with named arguments passed in arbitrary order.

Language designers for newer programming languages like Python recognize the value in named parameters with default values and arbitrary passing order and thus incorporated into the language:

PHP's emulation of this is the $args array which is used many places throughout WordPress, such as with WP_Query() which results in ability to robustly evolve the functions without worrying nearly as much about backward compatibility breakage.

With this change you loose all the IDE hinting you get from having named arguments.

True, but compared to the benefits of having an $args list having IDE hinting seems like a rather trivial benefit compared to the existing downside.

Besides, decent documentation resolves this concern, and maybe some IDEs can start provide hinting for array values (I'll bet PhpStorm would add it):

I don't see a strong benefit from this change.

There is clearly a benefit to this change as Mark's patch illustrates, but it seems the only explicit downside to this change you stated was lack of IDE hinting; is there any other objective reason this would not be a positive change?

comment:9 scribu3 years ago

I'm not a big fan of using an array for arguments when they are all required.

Did you look at the function definition recently?

function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $icon_url = '', $position = NULL ) {

$menu_title could default to $page_title and $capability could default to 'manage_options'. So, that would leave a total of 2 required arguments out of 7.

Last edited 3 years ago by scribu (previous) (diff)

comment:10 scribu3 years ago

  • Keywords has-patch added

johnjamesjacoby3 years ago

Patch applies clean. I like that it doesn't trigger deprecated notices yet. Refreshed to remove unnecessary brackets per coding standard.

comment:11 nacin3 years ago

  • Milestone 3.2 deleted
  • Resolution set to maybelater
  • Status changed from reopened to closed

We no longer need this for the UI refresh. Re-closing.

Note: See TracTickets for help on using tickets.