[wp-trac] [WordPress Trac] #64911: Incorrectly documented hooks

Fri Mar 20 08:04:33 UTC 2026

#64911: Incorrectly documented hooks
--------------------------+-----------------------------
 Reporter:  kkmuffme      |      Owner:  johnbillion
     Type:  defect (bug)  |     Status:  assigned
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  General       |    Version:  trunk
 Severity:  trivial       |   Keywords:
  Focuses:                |
--------------------------+-----------------------------
 Since I'm currently overhauling the wp-hooks/generator (https://github.com
 /wp-hooks/generator/pull/23 it's done but not pushed, internal testing
 atm) used e.g. with static analysis tools like psalm and phpstan, there
 seem to be various docblock issues for various hooks.

 Fixing these is an ideal first issue for any new contributors to WP core.

 Also I'm open to feedback for those - if you think some of them are wrong
 or shouldn't be changed for reason X, please let me know.

 {{{
 Incorrect param name $meta for hook param 1, expected $meta_defaults for
 hook 'add_signup_meta' in file 'wp-signup.php' on line 504.
 Incorrect param name $link for hook param 1, expected $html_link for hook
 'login_site_html_link' in file 'wp-login.php' on line 349.
 Incorrect param name $items for hook param 3, expected $post_ids for hook
 'handle_bulk_actions-{$screen}' in file 'wp-admin/edit.php' on line 222.
 Incorrect param name $redirect_url for hook param 1, expected $referer for
 hook 'handle_network_bulk_actions-{$screen}' in file 'wp-admin/network
 /site-themes.php' on line 139.
 Incorrect param name $items for hook param 3, expected $themes for hook
 'handle_network_bulk_actions-{$screen}' in file 'wp-admin/network/site-
 themes.php' on line 139.
 Incorrect param name $site_id for hook param 4, expected $id for hook
 'handle_network_bulk_actions-{$screen}' in file 'wp-admin/network/site-
 themes.php' on line 139.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'wp_ajax_menu_quick_search_args' in file 'wp-admin/includes/nav-
 menu.php' on line 112.
 Incorrect param name $args for hook param 1, expected $query_args for hook
 'wp_ajax_menu_quick_search_args' in file 'wp-admin/includes/nav-menu.php'
 on line 112.
 Incorrect param name $status_links for hook param 1, expected
 $get_views_links for hook 'comment_status_links' in file 'wp-
 admin/includes/class-wp-comments-list-table.php' on line 354.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'wp_privacy_personal_data_erasers' in file 'wp-admin/includes
 /ajax-actions.php' on line 5182.
 Incorrect param name $output for hook param 1, expected $column_output for
 hook 'manage_users-network_custom_column' in file 'wp-admin/includes
 /class-wp-ms-users-list-table.php' on line 481.
 Incorrect param name $screen_id for hook param 2, expected $id for hook
 'screen_layout_columns' in file 'wp-admin/includes/class-wp-screen.php' on
 line 943.
 Incorrect param name $screen_settings for hook param 1, expected
 $_screen_settings for hook 'screen_settings' in file 'wp-admin/includes
 /class-wp-screen.php' on line 1021.
 Incorrect param name $path for hook param 1, expected $filepath for hook
 'load_image_to_edit_filesystempath' in file 'wp-admin/includes/image.php'
 on line 1218.
 Incorrect param name $results for hook param 3, expected $update_results
 for hook 'automatic_updates_debug_email' in file 'wp-admin/includes/class-
 wp-automatic-updater.php' on line 1741.
 Incorrect param name $actions for hook param 1, expected $_actions for
 hook 'bulk_actions-{$this->screen->id}' in file 'wp-admin/includes/class-
 wp-list-table.php' on line 591.
 Incorrect param name $args for hook param 1, expected $info for hook
 'debug_information' in file 'wp-admin/includes/class-wp-debug-data.php' on
 line 135.
 Missing docblock for hook 'importer_scheduled_cleanup' in file 'wp-
 admin/includes/import.php' on line 123.
 Incorrect param name $site for hook param 2, expected $_site for hook
 'display_site_states' in file 'wp-admin/includes/class-wp-ms-sites-list-
 table.php' on line 673.
 Incorrect param name $sitename for hook param 2, expected $site_name for
 hook 'wp_privacy_personal_data_email_subject' in file 'wp-admin/includes
 /privacy-tools.php' on line 659.
 Missing docblock for hook 'upgrader_scheduled_cleanup' in file 'wp-
 admin/includes/class-file-upload-upgrader.php' on line 113.
 Incorrect param name $data for hook param 2, expected $new_plugin_data for
 hook 'upgrader_overwrote_package' in file 'wp-admin/includes/class-plugin-
 upgrader.php' on line 169.
 Missing docblock for hook 'publish_future_post' in file 'wp-
 admin/includes/upgrade.php' on line 1294.
 Incorrect param name $ability_name for hook param 1, expected $name for
 hook 'wp_before_execute_ability' in file 'wp-includes/abilities-api/class-
 wp-ability.php' on line 631.
 Incorrect param name $ability_name for hook param 1, expected $name for
 hook 'wp_after_execute_ability' in file 'wp-includes/abilities-api/class-
 wp-ability.php' on line 652.
 Incorrect param name $commentdata for hook param 2, expected $comment_data
 for hook 'pre_comment_approved' in file 'wp-includes/comment.php' on line
 1346.
 Incorrect param name $allow_branching for hook param 1, expected
 $branching for hook 'customize_changeset_branching' in file 'wp-includes
 /class-wp-customize-manager.php' on line 811.
 Incorrect param name $context for hook param 2, expected $filter_context
 for hook 'customize_changeset_save_data' in file 'wp-includes/class-wp-
 customize-manager.php' on line 2905.
 Incorrect param name $block_type for hook param 2, expected $name for hook
 'register_block_type_args' in file 'wp-includes/class-wp-block-type.php'
 on line 573.
 Incorrect param name $data for hook param 1, expected $data2html for hook
 'oembed_result' in file 'wp-includes/class-wp-oembed.php' on line 430.
 Incorrect param name $class_name for hook param 1, expected $classname for
 hook 'block_default_classname' in file 'wp-includes/block-supports
 /generated-classname.php' on line 36.
 Incorrect param name $post_type for hook param 2, expected $name for hook
 'register_post_type_args' in file 'wp-includes/class-wp-post-type.php' on
 line 501.
 Incorrect param name $post_type for hook param 2, expected $name for hook
 'register_{$post_type}_post_type_args' in file 'wp-includes/class-wp-post-
 type.php' on line 522.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'role_has_cap' in file 'wp-includes/class-wp-role.php' on line
 95.
 Incorrect param name $quality for hook param 1, expected $default_quality
 for hook 'wp_editor_set_quality' in file 'wp-includes/class-wp-image-
 editor.php' on line 269.
 Incorrect param name $mime_type for hook param 1, expected
 $default_mime_type for hook 'image_editor_default_mime_type' in file 'wp-
 includes/class-wp-image-editor.php' on line 393.
 Incorrect param name $blog_id for hook param 1, expected $site_id for hook
 'wpmu_blog_updated' in file 'wp-includes/ms-blogs.php' on line 35.
 Incorrect param name $output for hook param 1, expected $filtered_output
 for hook 'wp_finalized_template_enhancement_output_buffer' in file 'wp-
 includes/template.php' on line 1058.
 Incorrect param name $small_network for hook param 1, expected
 $is_small_network for hook 'enable_live_network_counts' in file 'wp-
 includes/ms-functions.php' on line 2512.
 Incorrect param name $subdirectory_reserved_names for hook param 1,
 expected $names for hook 'subdirectory_reserved_names' in file 'wp-
 includes/ms-functions.php' on line 2768.
 Incorrect param name $pre_option for hook param 1, expected $pre for hook
 'pre_option' in file 'wp-includes/option.php' on line 150.
 Documented 3 params, but 4 hook params provided for hook
 'wp_default_autoload_value' in file 'wp-includes/option.php' on line 1333.
 Incorrect param name $pre_option for hook param 1, expected $pre for hook
 'pre_site_option' in file 'wp-includes/option.php' on line 2057.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'pre_site_transient_{$transient}' in file 'wp-
 includes/option.php' on line 2582.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'is_post_type_viewable' in file 'wp-includes/post.php' on line
 2442.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'is_post_status_viewable' in file 'wp-includes/post.php' on line
 2494.
 Missing docblock for hook 'publish_future_post' in file 'wp-
 includes/post.php' on line 5402.
 Missing docblock for hook 'publish_future_post' in file 'wp-
 includes/post.php' on line 7985.
 Incorrect param name $html for hook param 1, expected $output for hook
 'wp_list_bookmarks' in file 'wp-includes/bookmark-template.php' on line
 321.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'wp_robots' in file 'wp-includes/robots-template.php' on line 32.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'wp_get_attachment_image_src' in file 'wp-includes/media.php' on
 line 1027.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'wp_img_tag_add_auto_sizes' in file 'wp-includes/media.php' on
 line 2024.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'pre_attachment_url_to_postid' in file 'wp-includes/media.php' on
 line 5526.
 Incorrect param name $default_header_enforced_contexts for hook param 1,
 expected $header_enforced_contexts for hook
 'wp_loading_optimization_force_header_contexts' in file 'wp-
 includes/media.php' on line 6116.
 Incorrect param name $number for hook param 1, expected $excerpt_length
 for hook 'excerpt_length' in file 'wp-includes/formatting.php' on line
 4019.
 Incorrect param name $taxonomy for hook param 2, expected $name for hook
 'register_taxonomy_args' in file 'wp-includes/class-wp-taxonomy.php' on
 line 316.
 Incorrect param name $taxonomy for hook param 2, expected $name for hook
 'register_{$taxonomy}_taxonomy_args' in file 'wp-includes/class-wp-
 taxonomy.php' on line 337.
 Incorrect param name $user_id for hook param 1, expected $ID for hook
 'add_user_role' in file 'wp-includes/class-wp-user.php' on line 575.
 Incorrect param name $user_id for hook param 1, expected $ID for hook
 'remove_user_role' in file 'wp-includes/class-wp-user.php' on line 603.
 Incorrect param name $user_id for hook param 1, expected $ID for hook
 'set_user_role' in file 'wp-includes/class-wp-user.php' on line 663.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'user_has_cap' in file 'wp-includes/class-wp-user.php' on line
 821.
 Hook params must be documented only with @param to avoid side-effects in
 static analysis, but @return tag found for hook
 'block_core_social_link_get_services' in file 'wp-includes/blocks/social-
 link.php' on line 349.
 Incorrect param name $stylesheets for hook param 1, expected $mce_css for
 hook 'mce_css' in file 'wp-includes/class-wp-editor.php' on line 600.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'wp_enqueue_editor' in file 'wp-includes/class-wp-editor.php' on
 line 893.
 Incorrect param name $comments for hook param 1, expected $comments_flat
 for hook 'comments_array' in file 'wp-includes/comment-template.php' on
 line 1589.
 Incorrect param name $args_comment_field for hook param 1, expected $field
 for hook 'comment_form_field_comment' in file 'wp-includes/comment-
 template.php' on line 2807.
 Incorrect param name $post for hook param 2, expected $item for hook
 'rest_prepare_wp_font_face' in file 'wp-includes/rest-api/endpoints/class-
 wp-rest-font-faces-controller.php' on line 483.
 Incorrect param name $item for hook param 2, expected $taxonomy for hook
 'rest_prepare_taxonomy' in file 'wp-includes/rest-api/endpoints/class-wp-
 rest-taxonomies-controller.php' on line 301.
 Incorrect param name $post for hook param 2, expected $item for hook
 'rest_prepare_wp_font_family' in file 'wp-includes/rest-api/endpoints
 /class-wp-rest-font-families-controller.php' on line 271.
 Incorrect param name $nav_menu_item for hook param 1, expected $menu_item
 for hook 'rest_delete_nav_menu_item' in file 'wp-includes/rest-
 api/endpoints/class-wp-rest-menu-items-controller.php' on line 329.
 Incorrect param name $where for hook param 1, expected $where_prepared for
 hook 'get_{$adjacent}_post_where' in file 'wp-includes/link-template.php'
 on line 1991.
 Incorrect param name $keys for hook param 1, expected
 $wp_revisioned_meta_keys for hook 'wp_post_revision_meta_keys' in file
 'wp-includes/revision.php' on line 584.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'schedule_event' in file 'wp-includes/cron.php' on line 179.
 Missing docblock for hook '$hook' in file 'wp-includes/cron.php' on line
 439.
 Incorrect param name $args for hook param 3, expected $hook for hook
 'wp_next_scheduled' in file 'wp-includes/cron.php' on line 859.
 Documented 3 params, but 4 hook params provided for hook
 'wp_next_scheduled' in file 'wp-includes/cron.php' on line 859.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'pre_wp_mail' in file 'wp-includes/pluggable.php' on line 231.
 Incorrect param name $message for hook param 1, expected $get_debug for
 hook 'recovery_email_debug_info' in file 'wp-includes/class-wp-recovery-
 mode-email-service.php' on line 150.
 Missing docblock for hook 'pre_option_enable_xmlrpc' in file 'wp-includes
 /class-wp-xmlrpc-server.php' on line 194.
 Missing docblock for hook 'option_enable_xmlrpc' in file 'wp-includes
 /class-wp-xmlrpc-server.php' on line 196.
 Incorrect param name $link for hook param 1, expected $route for hook
 'rest_queried_resource_route' in file 'wp-includes/rest-api.php' on line
 3334.
 Incorrect param name $is_request_endpoint for hook param 1, expected
 $is_rest_endpoint for hook 'wp_is_rest_endpoint' in file 'wp-includes
 /rest-api.php' on line 3488.
 Incorrect param name $block for hook param 2, expected $parsed_block for
 hook 'render_block' in file 'wp-includes/class-wp-block.php' on line 651.
 Incorrect param name $block for hook param 2, expected $parsed_block for
 hook 'render_block_{$this->name}' in file 'wp-includes/class-wp-block.php'
 on line 666.
 Incorrect param name $block_name for hook param 2, expected $name for hook
 'enqueue_empty_block_content_assets' in file 'wp-includes/class-wp-
 block.php' on line 704.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'allowed_block_types_all' in file 'wp-includes/block-editor.php'
 on line 127.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'allowed_block_types' in file 'wp-includes/block-editor.php' on
 line 142.
 Incorrect param name $default_value for hook param 1, expected $value for
 hook 'customize_value_{$id_base}' in file 'wp-includes/class-wp-customize-
 setting.php' on line 773.
 Incorrect param name $id for hook param 1, expected $blog_id for hook
 'clean_site_cache' in file 'wp-includes/ms-site.php' on line 1007.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'wp_script_attributes' in file 'wp-includes/script-loader.php' on
 line 2924.
 Found invalid 'boolean' JS type, but expected PHP type 'bool' in docblock
 for hook 'wp_inline_script_attributes' in file 'wp-includes/script-
 loader.php' on line 3027.
 Incorrect param name $defaults for hook param 1, expected
 $query_var_defaults for hook 'get_terms_defaults' in file 'wp-includes
 /class-wp-term-query.php' on line 260.
 Incorrect param name $args for hook param 2, expected $query_vars for hook
 'get_terms_orderby' in file 'wp-includes/class-wp-term-query.php' on line
 956.
 }}}

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