WordPress.org

Make WordPress Core

Opened 3 years ago

#40757 new defect (bug)

Standardize Application of 'the_category' Filter

Reported by: bcworkz Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version: 4.7.4
Component: Taxonomy Keywords:
Focuses: Cc:
PR Number:

Description

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.

Attachments (1)

40757.patch (3.3 KB) - added by bcworkz 3 years ago.
Provide 2nd & 3rd parms

Download all attachments as: .zip

Change History (1)

@bcworkz
3 years ago

Provide 2nd & 3rd parms

Note: See TracTickets for help on using tickets.