Standardize Application of 'the_category' Filter

[bcworkz]

According to the ​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 #39130 may be related.

For reference, the documented application of 'the_category' that passes three parameters is in the declaration for 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 ​Forums.

[bcworkz]

Provide 2nd & 3rd parms

[SergeyBiryukov]

Hi there, welcome back to WordPress Trac!

Thanks for the ticket, sorry it took so long for someone to get back to you.

Looks like this was fixed in [41221] / #38462.