[wp-trac] [WordPress Trac] #10441: Show warning when deprecated hook is registered

[WordPress Trac]

#10441: Show warning when deprecated hook is registered
------------------------------------+---------------------------
 Reporter:  sirzooro                |       Owner:  boonebgorges
     Type:  feature request         |      Status:  accepted
 Priority:  normal                  |   Milestone:  4.6
Component:  Plugins                 |     Version:
 Severity:  normal                  |  Resolution:
 Keywords:  dev-feedback has-patch  |     Focuses:
------------------------------------+---------------------------

Comment (by boonebgorges):

 Thanks for chiming in, @DrewAPicture.

 > Do we have any idea of the scope this would be applied in the current
 core landscape? I

 [attachment:deprecated-hooks.txt] is a rough list of existing hooks marked
 `@deprecated`. (`$ pcregrep -nrM
 "\@deprecated[^;]+(apply_filters|do_action)" src/ > ~/deprecated-
 hooks.txt`, with a bit of formatting cleanup). I don't think it's
 necessarily the case that we need to start throwing notices in all these
 cases - as in the case of `_deprecated_function()` and friends, we should
 be judicious - but it's a starting place.

 > And how would you propose documenting these new function calls in-place?
 Simply adding @deprecated tags in the hook docs?

 Good question. My suggestion is to keep the inline hook docs when
 deprecating, so that

 {{{
         /**
          * Filter the fields to select in the terms query.
          *
          * Field lists modified using this filter will only modify the
 term fields returned
          * by the function when the `$fields` parameter set to 'count' or
 'all'. In all other
          * cases, the term fields in the results array will be determined
 by the `$fields`
          * parameter alone.
          *
          * Use of this filter can result in unpredictable behavior, and is
 not recommended.
          *
          * @since 2.8.0
          *
          * @param array $selects    An array of fields to select for the
 terms query.
          * @param array $args       An array of term query arguments.
          * @param array $taxonomies An array of taxonomies.
          */
         $fields = implode( ', ', apply_filters( 'get_terms_fields',
 $selects, $args, $taxonomies ) );
 }}}

 becomes

 {{{
         /**
          * Filter the fields to select in the terms query.
          *
          * Field lists modified using this filter will only modify the
 term fields returned
          * by the function when the `$fields` parameter set to 'count' or
 'all'. In all other
          * cases, the term fields in the results array will be determined
 by the `$fields`
          * parameter alone.
          *
          * Use of this filter can result in unpredictable behavior, and is
 not recommended.
          *
          * @since 2.8.0
          *
          * @param array $selects    An array of fields to select for the
 terms query.
          * @param array $args       An array of term query arguments.
          * @param array $taxonomies An array of taxonomies.
          */
         $fields = implode( ', ', apply_filters_deprecated(
 'get_terms_fields', array( $selects, $args, $taxonomies ), '4.6.0' ) );
 }}}

 I presume that this will mean an update to phpdoc-parser, so that it knows
 (a) to look for the new function names, (b) that they count as "hooks".
 Presumably the parser should also (c) recognize that the
 `get_terms_fields` hook in the context of `apply_filters_deprecated()` is
 *the very same hook* as in the context of `apply_filters()`, so that any
 metadata (like user-submitted notes) are not lost when the filter is
 deprecated.

 I've started looking at phpdoc-parser, and it looks like (a) and (b)
 should be relatively easy to implement. It looks like (c) should
 automatically be the case - "hooks" are a single post type, identified by
 `post_name = $hook_name`, and the hook name will not be changing on
 deprecation. The parser should also recognize that a hook is being
 deprecated, and mark it as such, but at a glance it looks like this may
 just work too.

 Does this all seem correct to you? Your comment reminds me that this is
 perhaps more of a change from the documentation side than from the core
 side, so I want to make sure that we get it right from your point of view.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/10441#comment:29>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform