[wp-trac] [WordPress Trac] #15067: Deprecate exiting admin menu functions and add new ones that accept an $args parameter instead

[WordPress Trac]

#15067: Deprecate exiting admin menu functions and add new ones that accept an
$args parameter instead
----------------------------+-----------------------
 Reporter:  mikeschinkel    |       Owner:
     Type:  enhancement     |      Status:  reopened
 Priority:  normal          |   Milestone:  3.2
Component:  Administration  |     Version:
 Severity:  normal          |  Resolution:
 Keywords:                  |
----------------------------+-----------------------

Comment (by mikeschinkel):

 Replying to [comment:5 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 [comment:6 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 [comment:7 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?

-- 
Ticket URL: <http://core.trac.wordpress.org/ticket/15067#comment:8>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software