[wp-trac] [WordPress Trac] #14671: Deprecate the "accepted args" argument in add_filter() and add_action()

[WordPress Trac]

#14671: Deprecate the "accepted args" argument in add_filter() and add_action()
-------------------------+-----------------------------
 Reporter:  markjaquith  |       Owner:
     Type:  enhancement  |      Status:  new
 Priority:  normal       |   Milestone:  Future Release
Component:  Plugins      |     Version:
 Severity:  normal       |  Resolution:
 Keywords:  has-patch    |
-------------------------+-----------------------------

Comment (by westonruter):

 Replying to [comment:26 rmccue]:
 > I use [https://gist.github.com/5022591d312952d1245a#file-wp-
 includes_class-wp-json-server-php-L389 parameter matching] using
 Reflection in my own code and it's still reasonably fast. However, with
 this specific issue, we should just be able to pass all the parameters in
 (as if you set `$accepted_args` to `PHP_INT_MAX`) without issue, and use
 `$accepted_args` as a fallback to limit it (I can't think of any good
 reason not to, given that we have `current_filter`).

 There are two reasons why letting `PHP_INT_MAX` be the default value for
 `$accepted_args` would be undesirable, as I understand from chatting with
 markjaquith this weekend at WordCamp Phoenix:

 1. For internal PHP functions, if you pass more arguments than the
 function is defined to take, it will issue a warning, for example: `PHP
 Warning:  strtoupper() expects exactly 1 parameter, 3 given`.
 2. For user-defined functions that have optional arguments, sometimes they
 are designed to behave differently when additional arguments are supplied.
 If the developer is not aware of a filter being supplied extra arguments,
 they may assume that any argument defaults they define in their function
 will be used, only to be surprised when any extra arguments for the filter
 get supplied the function's optional arguments. This is the point that
 jacobsantos makes above:
 http://core.trac.wordpress.org/ticket/14671?replyto=26#comment:7

 The 2nd point above would actually be a potential issue with my patch
 because it uses Reflection's `getNumberOfParameters` method instead of
 `getNumberOfRequiredParameters`. Perhaps the latter would be a more
 suitable default. In any case, if the default is not correct, the
 developer may supply the 4th argument.

 On a completely different line of thinking, another option would be to
 eliminate the 4th argument and to let the 3rd parameter be a WP query arg
 string/array. This would not only make the code more readable (as the use
 of many positional parameters can be poor form), but it would also allow
 the `accepted_args` be supplied without having to supply the `priority`:

 {{{
 Index: wp-includes/plugin.php
 ===================================================================
 --- wp-includes/plugin.php      (revision 23307)
 +++ wp-includes/plugin.php      (working copy)
 @@ -62,8 +62,18 @@
   * @param int $accepted_args optional. The number of arguments the
 function accept (default 1).
   * @return boolean true
   */
 -function add_filter($tag, $function_to_add, $priority = 10,
 $accepted_args = 1) {
 +function add_filter($tag, $function_to_add, $options = '', $deprecated =
 1) {
         global $wp_filter, $merged_filters;
 +       if (is_numeric($options)) {
 +               _deprecated_argument(__FUNCTION__, '3.6', 'Supply the
 accepted_args in the 3rd argument options');
 +               $priority = $options;
 +               $accepted_args = $deprecated;
 +       } else {
 +               extract(wp_parse_args($options, array(
 +                       'priority' => 10,
 +                       'accepted_args' => 1,
 +               )));
 +       }

         $idx = _wp_filter_build_unique_id($tag, $function_to_add,
 $priority);
         $wp_filter[$tag][$priority][$idx] = array('function' =>
 $function_to_add, 'accepted_args' => $accepted_args);
 }}}

 Usage:

 {{{
 add_filter('the_content', 'translate_into_klingon', 'accepted_args=3');
 add_filter('the_content', 'translate_into_klingon', array( 'accepted_args'
 => 3 ));
 }}}

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