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

[mikeschinkel]

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.

[nacin]

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

[nacin]

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

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

[mikeschinkel]

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.)

[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.

[markjaquith]

First swing. No no params added yet.

[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.

[westi]

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.

[mikeschinkel]

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:

• ​http://docs.python.org/tutorial/controlflow.html#default-argument-values

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?

[scribu]

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.

[johnjamesjacoby]

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

[nacin]

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