Fix identical hooks with differing parameters

[johnbillion]

Two recent instances where a hook that is triggered in multiple places in core has ended up having differing parameters:

• #38057
• #38314

It would be ideal to have unit test coverage which scans core's PHP files for all instances of do_action and apply_filters, filters hooks that occur multiple times, and then verifies that every instance of the hook accepts the same number of parameters.

[jdgrimes]

The ​docs parser could probably do this easily, since it already scans for all of the hooks anyway. Maybe there is a way to integrate it into the tests process, but just to scan for the hooks?

[keesiemeijer]

To parse all php files is very expensive and should be avoided in unit tests. I've compiled a list (from the 4.6.1 parsed data) of hooks that are triggered in multiple places with differing parameters.

hook	function
​comment_text	​check_comment
​list_cats	​Walker_CategoryDropdown::start_el
​the_category	​wp_popular_terms_checklist
​the_category	​wp_link_category_checklist
​the_category	​Walker_Category_Checklist::start_el
​the_content	​do_trackbacks
​wp_update_nav_menu	​wp_nav_menu_update_menu_items
​the_permalink	​comment_form
​deleted_user	​wpmu_delete_user
​quick_edit_custom_box	​WP_Terms_List_Table::inline_edit
​restrict_manage_posts	​WP_Media_List_Table::extra_tablenav
​theme_action_links_{$stylesheet}	​WP_Themes_List_Table::display_rows
​theme_action_links	​WP_Themes_List_Table::display_rows
​admin_footer	​WP_Press_This::html

For now we should update these hooks with the right parameters. We could have the docs parser store these hooks when parsing and correct them after upgrading WP.

[johnbillion]

Thanks for that @keesiemeijer! Some of the inconsistencies there are a complete mess.

[keesiemeijer]

Yeah, maybe this should be changed into a task instead of a feature request. Should I create a separate ticket for that?

Meanwhile I've found some more oddities that should be cleaned up.

This one (in a deprecated function) is missing a parameter in the database because it's not documented.
​https://developer.wordpress.org/reference/hooks/the_content_rss/

These have differing parameter names in the DocBlock

hook	function
​the_comments	​WP_Comment_Query::get_comments
​the_sites	​WP_Site_Query::get_sites
​posts_join	​WP_Query::get_posts
​the_networks	​WP_Network_Query::get_networks

These have missing parameters in the DocBlock

hook	function
​get_avatar	​get_avatar
​show_post_locked_dialog	​_admin_notice_post_locked
​fallback_intermediate_image_sizes	​wp_generate_attachment_metadata

These have Concatenated dynamic hooks

hook	function
​the_author_{$field}	​the_author_meta
​get_the_author_{$field}	​get_the_author_meta
​customize_save_{$this->id_data[‘base’}]	​WP_Customize_Setting::save
​{$field}	​sanitize_bookmark_field
​{$field}	​sanitize_user_field
​{$field}	​sanitize_post_field
​default_option_{$option}	​update_option
​default_option_{$option}	​add_option
​uninstall_{$file}	​uninstall_plugin
​{$type}_send_to_editor_url	​wp_ajax_send_link_to_editor
​{$option}	​WP_Screen::render_per_page_options
​{$option}	​WP_List_Table::get_items_per_page
​handle_bulk_actions-{current_screen_id}*
​handle_network_bulk_actions-{current_screen_id}*

[keesiemeijer]

I've created a ticket for the concatenated dynamic hooks here: #39148

[johnbillion]

#40636 was marked as a duplicate.

[johnbillion]

I think we can drop the idea of unit testing this for now, and concentrate on fixing the differing parameters.

[johnbillion]

In 41215:

Docs: Fix various filter documentation.

See #38462, #41017

[johnbillion]

In 41216:

Docs: Add a missing docblock for the the_content_rss filter.

See #38462, #41017

[johnbillion]

In 41217:

General: Add missing parameters to instances of the the_permalink filter.

This ensures every instance of this filter receives the same parameters.

Props keesiemeijer for identifying the issue

See #38462

[johnbillion]

In 41219:

General: Fix various instances of incorrect filter docs and incorrect filter and action parameters.

Props keesiemeijer for identifying the issues

See #38462

[johnbillion]

In 41220:

General: Fix a typo introduced in [41219].

See #38462

[johnbillion]

In 41221:

General: Fix more instances of inconsistent parameters passed to various filters, plus fix some filter docs.

See #38462, #41017

[johnbillion]

Thanks again for those scans, @keesiemeijer . I've fixed all of the issues. The remaining issue is in #38057.

[SergeyBiryukov]

#40757 was marked as a duplicate.