From ae9eae8f64aa84b965ca1d67e13164826a493b52 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 21 Sep 2021 18:21:00 +0000 Subject: [PATCH] Docs: Document some more common names for dynamic hooks and standardise the phrasing used. Fixes #53581 Built from https://develop.svn.wordpress.org/trunk@51837 git-svn-id: http://core.svn.wordpress.org/trunk@51444 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/admin-header.php | 2 +- .../class-wp-plugin-install-list-table.php | 2 ++ wp-admin/includes/media.php | 2 +- wp-admin/includes/meta-boxes.php | 2 +- wp-admin/includes/misc.php | 2 +- wp-admin/plugin-install.php | 30 +++++++++++++--- wp-admin/user-edit.php | 2 +- wp-includes/category-template.php | 2 +- wp-includes/comment-template.php | 2 +- wp-includes/comment.php | 24 +++++++++++-- wp-includes/l10n.php | 8 ++--- wp-includes/meta.php | 36 +++++++++---------- wp-includes/post.php | 6 ++++ wp-includes/taxonomy.php | 10 +++--- wp-includes/version.php | 2 +- 15 files changed, 91 insertions(+), 41 deletions(-) diff --git a/wp-admin/admin-header.php b/wp-admin/admin-header.php index 7ee3d03b74..2f7ae3b8c5 100644 --- a/wp-admin/admin-header.php +++ b/wp-admin/admin-header.php @@ -132,7 +132,7 @@ do_action( 'admin_print_scripts' ); /** * Fires in head section for a specific admin page. * - * The dynamic portion of the hook, `$hook_suffix`, refers to the hook suffix + * The dynamic portion of the hook name, `$hook_suffix`, refers to the hook suffix * for the admin page. * * @since 2.1.0 diff --git a/wp-admin/includes/class-wp-plugin-install-list-table.php b/wp-admin/includes/class-wp-plugin-install-list-table.php index 59bce7b8d1..c214cd333b 100644 --- a/wp-admin/includes/class-wp-plugin-install-list-table.php +++ b/wp-admin/includes/class-wp-plugin-install-list-table.php @@ -225,6 +225,8 @@ class WP_Plugin_Install_List_Table extends WP_List_Table { * - `install_plugins_table_api_args_popular` * - `install_plugins_table_api_args_recommended` * - `install_plugins_table_api_args_upload` + * - `install_plugins_table_api_args_search` + * - `install_plugins_table_api_args_beta` * * @since 3.7.0 * diff --git a/wp-admin/includes/media.php b/wp-admin/includes/media.php index 7ad34a4566..3cb96b2bb4 100644 --- a/wp-admin/includes/media.php +++ b/wp-admin/includes/media.php @@ -577,7 +577,7 @@ function wp_iframe( $content_func, ...$args ) { * Fires in the admin header for each specific form tab in the legacy * (pre-3.5.0) media upload popup. * - * The dynamic portion of the hook, `$content_func`, refers to the form + * The dynamic portion of the hook name, `$content_func`, refers to the form * callback for the media upload type. * * @since 2.5.0 diff --git a/wp-admin/includes/meta-boxes.php b/wp-admin/includes/meta-boxes.php index 0dcc9f5e5c..193877ce96 100644 --- a/wp-admin/includes/meta-boxes.php +++ b/wp-admin/includes/meta-boxes.php @@ -1581,7 +1581,7 @@ function register_and_do_post_meta_boxes( $post ) { /** * Fires after all built-in meta boxes have been added, contextually for the given post type. * - * The dynamic portion of the hook, `$post_type`, refers to the post type of the post. + * The dynamic portion of the hook name, `$post_type`, refers to the post type of the post. * * Possible hook names include: * diff --git a/wp-admin/includes/misc.php b/wp-admin/includes/misc.php index 61d7698310..70f6edde2b 100644 --- a/wp-admin/includes/misc.php +++ b/wp-admin/includes/misc.php @@ -716,7 +716,7 @@ function set_screen_options() { /** * Filters a screen option value before it is set. * - * The dynamic portion of the hook, `$option`, refers to the option name. + * The dynamic portion of the hook name, `$option`, refers to the option name. * * Returning false from the filter will skip saving the current option. * diff --git a/wp-admin/plugin-install.php b/wp-admin/plugin-install.php index 0e01c44161..a8b4e333ab 100644 --- a/wp-admin/plugin-install.php +++ b/wp-admin/plugin-install.php @@ -63,8 +63,19 @@ wp_enqueue_script( 'updates' ); /** * Fires before each tab on the Install Plugins screen is loaded. * - * The dynamic portion of the action hook, `$tab`, allows for targeting - * individual tabs, for instance 'install_plugins_pre_plugin-information'. + * The dynamic portion of the hook name, `$tab`, allows for targeting + * individual tabs. + * + * Possible hook names include: + * + * - `install_plugins_pre_beta` + * - `install_plugins_pre_favorites` + * - `install_plugins_pre_featured` + * - `install_plugins_pre_plugin-information` + * - `install_plugins_pre_popular` + * - `install_plugins_pre_recommended` + * - `install_plugins_pre_search` + * - `install_plugins_pre_upload` * * @since 2.7.0 */ @@ -164,8 +175,19 @@ if ( 'upload' !== $tab ) { /** * Fires after the plugins list table in each tab of the Install Plugins screen. * - * The dynamic portion of the action hook, `$tab`, allows for targeting - * individual tabs, for instance 'install_plugins_plugin-information'. + * The dynamic portion of the hook name, `$tab`, allows for targeting + * individual tabs. + * + * Possible hook names include: + * + * - `install_plugins_beta` + * - `install_plugins_favorites` + * - `install_plugins_featured` + * - `install_plugins_plugin-information` + * - `install_plugins_popular` + * - `install_plugins_recommended` + * - `install_plugins_search` + * - `install_plugins_upload` * * @since 2.7.0 * diff --git a/wp-admin/user-edit.php b/wp-admin/user-edit.php index 0cd381caf2..9485aab20f 100644 --- a/wp-admin/user-edit.php +++ b/wp-admin/user-edit.php @@ -553,7 +553,7 @@ endif; /** * Filters a user contactmethod label. * - * The dynamic portion of the filter hook, `$name`, refers to + * The dynamic portion of the hook name, `$name`, refers to * each of the keys in the contact methods array. * * @since 2.9.0 diff --git a/wp-includes/category-template.php b/wp-includes/category-template.php index a10f9533c3..38c52a79a9 100644 --- a/wp-includes/category-template.php +++ b/wp-includes/category-template.php @@ -1343,7 +1343,7 @@ function get_the_term_list( $post_id, $taxonomy, $before = '', $sep = '', $after /** * Filters the term links for a given taxonomy. * - * The dynamic portion of the filter name, `$taxonomy`, refers + * The dynamic portion of the hook name, `$taxonomy`, refers * to the taxonomy slug. * * Possible hook names include: diff --git a/wp-includes/comment-template.php b/wp-includes/comment-template.php index a40a98d170..e45088729f 100644 --- a/wp-includes/comment-template.php +++ b/wp-includes/comment-template.php @@ -2646,7 +2646,7 @@ function comment_form( $args = array(), $post_id = null ) { /** * Filters a comment form field for display. * - * The dynamic portion of the filter hook, `$name`, refers to the name + * The dynamic portion of the hook name, `$name`, refers to the name * of the comment form field. * * Possible hook names include: diff --git a/wp-includes/comment.php b/wp-includes/comment.php index 5c4f2b5f3e..113bb2e719 100644 --- a/wp-includes/comment.php +++ b/wp-includes/comment.php @@ -1826,6 +1826,15 @@ function wp_transition_comment_status( $new_status, $old_status, $comment ) { * The dynamic portions of the hook name, `$old_status`, and `$new_status`, * refer to the old and new comment statuses, respectively. * + * Possible hook names include: + * + * - `comment_unapproved_to_approved` + * - `comment_spam_to_approved` + * - `comment_approved_to_unapproved` + * - `comment_spam_to_unapproved` + * - `comment_unapproved_to_spam` + * - `comment_approved_to_spam` + * * @since 2.7.0 * * @param WP_Comment $comment Comment object. @@ -1838,8 +1847,19 @@ function wp_transition_comment_status( $new_status, $old_status, $comment ) { * The dynamic portions of the hook name, `$new_status`, and `$comment->comment_type`, * refer to the new comment status, and the type of comment, respectively. * - * Typical comment types include an empty string (standard comment), 'pingback', - * or 'trackback'. + * Typical comment types include 'comment', 'pingback', or 'trackback'. + * + * Possible hook names include: + * + * - `comment_approved_comment` + * - `comment_approved_pingback` + * - `comment_approved_trackback` + * - `comment_unapproved_comment` + * - `comment_unapproved_pingback` + * - `comment_unapproved_trackback` + * - `comment_spam_comment` + * - `comment_spam_pingback` + * - `comment_spam_trackback` * * @since 2.7.0 * diff --git a/wp-includes/l10n.php b/wp-includes/l10n.php index 7699d92b1e..8347c226fa 100644 --- a/wp-includes/l10n.php +++ b/wp-includes/l10n.php @@ -191,7 +191,7 @@ function translate( $text, $domain = 'default' ) { /** * Filters text with its translation for a domain. * - * The dynamic portion of the hook, `$domain`, refers to the text domain. + * The dynamic portion of the hook name, `$domain`, refers to the text domain. * * @since 5.5.0 * @@ -259,7 +259,7 @@ function translate_with_gettext_context( $text, $context, $domain = 'default' ) /** * Filters text with its translation based on context information for a domain. * - * The dynamic portion of the hook, `$domain`, refers to the text domain. + * The dynamic portion of the hook name, `$domain`, refers to the text domain. * * @since 5.5.0 * @@ -482,7 +482,7 @@ function _n( $single, $plural, $number, $domain = 'default' ) { /** * Filters the singular or plural form of a string for a domain. * - * The dynamic portion of the hook, `$domain`, refers to the text domain. + * The dynamic portion of the hook name, `$domain`, refers to the text domain. * * @since 5.5.0 * @@ -542,7 +542,7 @@ function _nx( $single, $plural, $number, $context, $domain = 'default' ) { /** * Filters the singular or plural form of a string with gettext context for a domain. * - * The dynamic portion of the hook, `$domain`, refers to the text domain. + * The dynamic portion of the hook name, `$domain`, refers to the text domain. * * @since 5.5.0 * diff --git a/wp-includes/meta.php b/wp-includes/meta.php index fc7d125fce..310b10f933 100644 --- a/wp-includes/meta.php +++ b/wp-includes/meta.php @@ -56,7 +56,7 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique = /** * Short-circuits adding metadata of a specific type. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * Returning a non-null value will effectively short-circuit the function. * @@ -96,7 +96,7 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique = /** * Fires immediately before meta of a specific type is added. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * * Possible hook names include: @@ -134,7 +134,7 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique = /** * Fires immediately after meta of a specific type is added. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * * Possible hook names include: @@ -209,7 +209,7 @@ function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_ /** * Short-circuits updating metadata of a specific type. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * Returning a non-null value will effectively short-circuit the function. * @@ -268,7 +268,7 @@ function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_ /** * Fires immediately before updating metadata of a specific type. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * * Possible hook names include: @@ -314,7 +314,7 @@ function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_ /** * Fires immediately after updating metadata of a specific type. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * * Possible hook names include: @@ -401,7 +401,7 @@ function delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $ /** * Short-circuits deleting metadata of a specific type. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * Returning a non-null value will effectively short-circuit the function. * @@ -456,7 +456,7 @@ function delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $ /** * Fires immediately before deleting metadata of a specific type. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * * Possible hook names include: @@ -506,7 +506,7 @@ function delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $ /** * Fires immediately after deleting metadata of a specific type. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * * Possible hook names include: @@ -608,7 +608,7 @@ function get_metadata_raw( $meta_type, $object_id, $meta_key = '', $single = fal /** * Short-circuits the return value of a meta field. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * Returning a non-null value will effectively short-circuit the function. * @@ -692,7 +692,7 @@ function get_metadata_default( $meta_type, $object_id, $meta_key, $single = fals /** * Filters the default metadata value for a specified meta key and object. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * * Possible filter names include: @@ -805,7 +805,7 @@ function get_metadata_by_mid( $meta_type, $meta_id ) { /** * Short-circuits the return value when fetching a meta field by meta ID. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * Returning a non-null value will effectively short-circuit the function. * @@ -879,7 +879,7 @@ function update_metadata_by_mid( $meta_type, $meta_id, $meta_value, $meta_key = /** * Short-circuits updating metadata of a specific type by meta ID. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * Returning a non-null value will effectively short-circuit the function. * @@ -1002,7 +1002,7 @@ function delete_metadata_by_mid( $meta_type, $meta_id ) { /** * Short-circuits deleting metadata of a specific type by meta ID. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * Returning a non-null value will effectively short-circuit the function. * @@ -1036,7 +1036,7 @@ function delete_metadata_by_mid( $meta_type, $meta_id ) { /** * Fires immediately before deleting post or comment metadata of a specific type. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta + * The dynamic portion of the hook name, `$meta_type`, refers to the meta * object type (post or comment). * * Possible hook names include: @@ -1067,7 +1067,7 @@ function delete_metadata_by_mid( $meta_type, $meta_id ) { /** * Fires immediately after deleting post or comment metadata of a specific type. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta + * The dynamic portion of the hook name, `$meta_type`, refers to the meta * object type (post or comment). * * Possible hook names include: @@ -1128,7 +1128,7 @@ function update_meta_cache( $meta_type, $object_ids ) { /** * Short-circuits updating the metadata cache of a specific type. * - * The dynamic portion of the hook, `$meta_type`, refers to the meta object type + * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * Returning a non-null value will effectively short-circuit the function. * @@ -1774,7 +1774,7 @@ function get_object_subtype( $object_type, $object_id ) { /** * Filters the object subtype identifier for a non-standard object type. * - * The dynamic portion of the hook, `$object_type`, refers to the meta object type + * The dynamic portion of the hook name, `$object_type`, refers to the meta object type * (post, comment, term, user, or any other type with an associated meta table). * * Possible hook names include: diff --git a/wp-includes/post.php b/wp-includes/post.php index 3ec68625a5..1adc89908a 100644 --- a/wp-includes/post.php +++ b/wp-includes/post.php @@ -5112,6 +5112,12 @@ function wp_transition_post_status( $new_status, $old_status, $post ) { * The dynamic portions of the hook name, `$new_status` and `$old_status`, * refer to the old and new post statuses, respectively. * + * Possible hook names include: + * + * - `draft_to_publish` + * - `publish_to_trash` + * - `pending_to_draft` + * * @since 2.3.0 * * @param WP_Post $post Post object. diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php index 531a6f537b..104da64a87 100644 --- a/wp-includes/taxonomy.php +++ b/wp-includes/taxonomy.php @@ -945,7 +945,7 @@ function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) { /** * Filters a taxonomy term object. * - * The dynamic portion of the filter name, `$taxonomy`, refers + * The dynamic portion of the hook name, `$taxonomy`, refers * to the slug of the term's taxonomy. * * Possible hook names include: @@ -1659,7 +1659,7 @@ function sanitize_term_field( $field, $value, $term_id, $taxonomy, $context ) { /** * Filters a term field to edit before it is sanitized. * - * The dynamic portion of the filter name, `$field`, refers to the term field. + * The dynamic portion of the hook name, `$field`, refers to the term field. * * @since 2.3.0 * @@ -1692,7 +1692,7 @@ function sanitize_term_field( $field, $value, $term_id, $taxonomy, $context ) { /** * Filters a term field value before it is sanitized. * - * The dynamic portion of the filter name, `$field`, refers to the term field. + * The dynamic portion of the hook name, `$field`, refers to the term field. * * @since 2.3.0 * @@ -1731,7 +1731,7 @@ function sanitize_term_field( $field, $value, $term_id, $taxonomy, $context ) { /** * Filters the term field for use in RSS. * - * The dynamic portion of the filter name, `$field`, refers to the term field. + * The dynamic portion of the hook name, `$field`, refers to the term field. * * @since 2.3.0 * @@ -1757,7 +1757,7 @@ function sanitize_term_field( $field, $value, $term_id, $taxonomy, $context ) { /** * Filters the term field sanitized for display. * - * The dynamic portion of the filter name, `$field`, refers to the term field name. + * The dynamic portion of the hook name, `$field`, refers to the term field name. * * @since 2.3.0 * diff --git a/wp-includes/version.php b/wp-includes/version.php index 7675b6a2f2..3d5e40df4c 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '5.9-alpha-51832'; +$wp_version = '5.9-alpha-51837'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.