Upstream/WordPress
1
0
Fork 0
mirror of https://github.com/WordPress/WordPress.git synced 2024-06-26 14:54:57 +02:00
Code Issues Projects Releases Wiki Activity

Docs: Document some more common names for dynamic hooks and standardise the phrasing used.

Browse Source 
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
This commit is contained in:
John Blackbourn 2021-09-21 18:21:00 +00:00
parent 70f1109c9f
commit ae9eae8f64
15 changed files with 91 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
wp-admin/admin-header.php
View File

@ -132,7 +132,7 @@ do_action( 'admin_print_scripts' );
/** /**
* Fires in head section for a specific admin page. * 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. * for the admin page.
* *
* @since 2.1.0 * @since 2.1.0

2
wp-admin/includes/class-wp-plugin-install-list-table.php
View File

@ -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_popular`
* - `install_plugins_table_api_args_recommended` * - `install_plugins_table_api_args_recommended`
* - `install_plugins_table_api_args_upload` * - `install_plugins_table_api_args_upload`
* - `install_plugins_table_api_args_search`
* - `install_plugins_table_api_args_beta`
* *
* @since 3.7.0 * @since 3.7.0
* *

2
wp-admin/includes/media.php
View File

@ -577,7 +577,7 @@ function wp_iframe( $content_func, ...$args ) {
* Fires in the admin header for each specific form tab in the legacy * Fires in the admin header for each specific form tab in the legacy
* (pre-3.5.0) media upload popup. * (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. * callback for the media upload type.
* *
* @since 2.5.0 * @since 2.5.0

2
wp-admin/includes/meta-boxes.php
View File

@ -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. * 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: * Possible hook names include:
* *

2
wp-admin/includes/misc.php
View File

@ -716,7 +716,7 @@ function set_screen_options() {
/** /**
* Filters a screen option value before it is set. * 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. * Returning false from the filter will skip saving the current option.
* *

30
wp-admin/plugin-install.php
View File

@ -63,8 +63,19 @@ wp_enqueue_script( 'updates' );
/** /**
* Fires before each tab on the Install Plugins screen is loaded. * Fires before each tab on the Install Plugins screen is loaded.
* *
* The dynamic portion of the action hook, `$tab`, allows for targeting * The dynamic portion of the hook name, `$tab`, allows for targeting
* individual tabs, for instance 'install_plugins_pre_plugin-information'. * 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 * @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. * 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 * The dynamic portion of the hook name, `$tab`, allows for targeting
* individual tabs, for instance 'install_plugins_plugin-information'. * 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 * @since 2.7.0
* *

2
wp-admin/user-edit.php
View File

@ -553,7 +553,7 @@ endif;
/** /**
* Filters a user contactmethod label. * 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. * each of the keys in the contact methods array.
* *
* @since 2.9.0 * @since 2.9.0

2
wp-includes/category-template.php
View File

@ -1343,7 +1343,7 @@ function get_the_term_list( $post_id, $taxonomy, $before = '', $sep = '', $after
/** /**
* Filters the term links for a given taxonomy. * 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. * to the taxonomy slug.
* *
* Possible hook names include: * Possible hook names include:

2
wp-includes/comment-template.php
View File

@ -2646,7 +2646,7 @@ function comment_form( $args = array(), $post_id = null ) {
/** /**
* Filters a comment form field for display. * 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. * of the comment form field.
* *
* Possible hook names include: * Possible hook names include:

24
wp-includes/comment.php
View File

@ -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`, * The dynamic portions of the hook name, `$old_status`, and `$new_status`,
* refer to the old and new comment statuses, respectively. * 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 * @since 2.7.0
* *
* @param WP_Comment $comment Comment object. * @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`, * 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. * refer to the new comment status, and the type of comment, respectively.
* *
* Typical comment types include an empty string (standard comment), 'pingback', * Typical comment types include 'comment', 'pingback', or 'trackback'.
* 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 * @since 2.7.0
* *

8
wp-includes/l10n.php
View File

@ -191,7 +191,7 @@ function translate( $text, $domain = 'default' ) {
/** /**
* Filters text with its translation for a domain. * 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 * @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. * 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 * @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. * 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 * @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. * 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 * @since 5.5.0
* *

36
wp-includes/meta.php
View File

@ -56,7 +56,7 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique =
/** /**
* Short-circuits adding metadata of a specific type. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* Returning a non-null value will effectively short-circuit the function. * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* *
* Possible hook names include: * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* *
* Possible hook names include: * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* Returning a non-null value will effectively short-circuit the function. * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* *
* Possible hook names include: * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* *
* Possible hook names include: * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* Returning a non-null value will effectively short-circuit the function. * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* *
* Possible hook names include: * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* *
* Possible hook names include: * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* Returning a non-null value will effectively short-circuit the function. * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* *
* Possible filter names include: * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* Returning a non-null value will effectively short-circuit the function. * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* Returning a non-null value will effectively short-circuit the function. * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* Returning a non-null value will effectively short-circuit the function. * 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. * 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). * object type (post or comment).
* *
* Possible hook names include: * 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. * 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). * object type (post or comment).
* *
* Possible hook names include: * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* Returning a non-null value will effectively short-circuit the function. * 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. * 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). * (post, comment, term, user, or any other type with an associated meta table).
* *
* Possible hook names include: * Possible hook names include:

6
wp-includes/post.php
View File

@ -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`, * The dynamic portions of the hook name, `$new_status` and `$old_status`,
* refer to the old and new post statuses, respectively. * 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 * @since 2.3.0
* *
* @param WP_Post $post Post object. * @param WP_Post $post Post object.

10
wp-includes/taxonomy.php
View File

@ -945,7 +945,7 @@ function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
/** /**
* Filters a taxonomy term object. * 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. * to the slug of the term's taxonomy.
* *
* Possible hook names include: * 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. * 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 * @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. * 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 * @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. * 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 * @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. * 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 * @since 2.3.0
* *

2
wp-includes/version.php
View File

@ -16,7 +16,7 @@
* *
* @global string $wp_version * @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. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.