[wp-trac] [WordPress Trac] #40757: Standardize Application of 'the_category' Filter

[WordPress Trac]

#40757: Standardize Application of 'the_category' Filter
--------------------------+-----------------------------
 Reporter:  bcworkz       |      Owner:
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  Taxonomy      |    Version:  4.7.4
 Severity:  normal        |   Keywords:
  Focuses:                |
--------------------------+-----------------------------
 According to the
 [https://developer.wordpress.org/reference/functions/get_the_category_list/
 Code Reference], application of 'the_category' filter passes three
 parameters (line 210). There are a number of instances in core where only
 the first parameter is passed. This causes PHP warnings to be issued when
 plugin or theme code that hooks 'the_category' asks for more than the
 first parameter to be passed when their callback is added. For example
 {{{add_filter('the_category', 'add_class_to_category', 10, 3 );}}}

 All applications of this filter in core should comply with documentation
 by passing all three of the documented parameters, even if it is just the
 default empty string. Granted, plugin and theme devs can prevent the
 warning by providing default parameter values for their callback function
 or by conditionally adding their callback only when {{{!is_admin()}}}, but
 many people using this filter are not experienced developers, they are
 site owners tweaking their installation using very minimal PHP skills.
 They are not capable of adapting to situations that do not match the
 provided documentation. Core code should consistently comply with the
 provided documentation.

 Alternately, update documentation to clearly indicate the two additional
 parameters are optional. For the reasons just mentioned, documentation
 would need some good examples for how to avoid PHP warnings. Given
 people's propensity to not read documentation, I'm not convinced this is a
 good alternative. If it is the chosen direction Trac #[ticket:39130] may
 be related.

 For reference, the documented application of 'the_category' that passes
 three parameters is in the declaration for
 [https://core.trac.wordpress.org/browser/tags/4.7.4/src/wp-includes
 /category-template.php#L205 get_the_category_list()]. (Also at lines 135
 and 151)

 Locations that only pass one parameter (which are all other applications
 in core):
 source:tags/4.7.4/src/wp-admin/includes/class-walker-category-
 checklist.php#L99

 source:tags/4.7.4/src/wp-admin/includes/class-walker-category-
 checklist.php#L106

 source:tags/4.7.4/src/wp-admin/includes/template.php#L217

 source:tags/4.7.4/src/wp-admin/includes/template.php#L258

 source:tags/4.7.4/src/wp-admin/edit-tags.php#L540

 4.7.4 references are from my initial research, the included patch is for
 changeset:40663.

 Props to @biellebrunner and @csloisel for bringing attention to this in
 the [https://wordpress.org/support/topic/missing-argument-2-on-a-custom-
 function/ Forums].

--
Ticket URL: <https://core.trac.wordpress.org/ticket/40757>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform