From 347e83176898c3193de81faedd9c4573b54ea30a Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Mon, 29 Jun 2020 21:22:09 +0000 Subject: [PATCH] Docs: Improve documentation for the `$prev_value` parameter and return result of various metadata update functions. Props stevenlinx. Fixes #50502. See #49572. Built from https://develop.svn.wordpress.org/trunk@48214 git-svn-id: http://core.svn.wordpress.org/trunk@47983 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/comment.php | 6 ++++-- wp-includes/meta.php | 17 +++++++++++------ wp-includes/ms-site.php | 6 ++++-- wp-includes/post.php | 6 ++++-- wp-includes/taxonomy.php | 8 +++++--- wp-includes/user.php | 6 ++++-- wp-includes/version.php | 2 +- 7 files changed, 33 insertions(+), 18 deletions(-) diff --git a/wp-includes/comment.php b/wp-includes/comment.php index de6b392a2c..8246fc9bc5 100644 --- a/wp-includes/comment.php +++ b/wp-includes/comment.php @@ -517,9 +517,11 @@ function get_comment_meta( $comment_id, $key = '', $single = false ) { * @param string $meta_key Metadata key. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. * @param mixed $prev_value Optional. Previous value to check before updating. - * Default empty. + * If specified, only update existing metadata entries with + * this value. Otherwise, update all entries. Default empty. * @return int|bool Meta ID if the key didn't exist, true on successful update, - * false on failure. + * false on failure or if the value passed to the function + * is the same as the one that is already in the database. */ function update_comment_meta( $comment_id, $meta_key, $meta_value, $prev_value = '' ) { return update_metadata( 'comment', $comment_id, $meta_key, $meta_value, $prev_value ); diff --git a/wp-includes/meta.php b/wp-includes/meta.php index cacb8be305..f434ef3b5c 100644 --- a/wp-includes/meta.php +++ b/wp-includes/meta.php @@ -148,10 +148,14 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique = * @param int $object_id ID of the object metadata is for. * @param string $meta_key Metadata key. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. - * @param mixed $prev_value Optional. If specified, only update existing metadata entries - * with this value. Otherwise, update all entries. Default empty. - * @return int|bool The new meta field ID if a field with the given key didn't exist and was - * therefore added, true on successful update, false on failure. + * @param mixed $prev_value Optional. Previous value to check before updating. + * If specified, only update existing metadata entries with + * this value. Otherwise, update all entries. Default empty. + * @return int|bool The new meta field ID if a field with the given key didn't exist + * and was therefore added, true on successful update, + * false on failure or if the value passed to the function + * is the same as the one that is already in the database. + */ function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_value = '' ) { global $wpdb; @@ -195,8 +199,9 @@ function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_ * @param int $object_id ID of the object metadata is for. * @param string $meta_key Metadata key. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. - * @param mixed $prev_value Optional. If specified, only update existing metadata entries - * with this value. Otherwise, update all entries. + * @param mixed $prev_value Optional. Previous value to check before updating. + * If specified, only update existing metadata entries with + * this value. Otherwise, update all entries. */ $check = apply_filters( "update_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $prev_value ); if ( null !== $check ) { diff --git a/wp-includes/ms-site.php b/wp-includes/ms-site.php index 5124c4ad50..7070baefd9 100644 --- a/wp-includes/ms-site.php +++ b/wp-includes/ms-site.php @@ -1107,9 +1107,11 @@ function get_site_meta( $site_id, $key = '', $single = false ) { * @param string $meta_key Metadata key. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. * @param mixed $prev_value Optional. Previous value to check before updating. - * Default empty. + * If specified, only update existing metadata entries with + * this value. Otherwise, update all entries. Default empty. * @return int|bool Meta ID if the key didn't exist, true on successful update, - * false on failure. + * false on failure or if the value passed to the function + * is the same as the one that is already in the database. */ function update_site_meta( $site_id, $meta_key, $meta_value, $prev_value = '' ) { return update_metadata( 'blog', $site_id, $meta_key, $meta_value, $prev_value ); diff --git a/wp-includes/post.php b/wp-includes/post.php index 1ab5ab1501..c76381ce95 100644 --- a/wp-includes/post.php +++ b/wp-includes/post.php @@ -2140,9 +2140,11 @@ function get_post_meta( $post_id, $key = '', $single = false ) { * @param string $meta_key Metadata key. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. * @param mixed $prev_value Optional. Previous value to check before updating. - * Default empty. + * If specified, only update existing metadata entries with + * this value. Otherwise, update all entries. Default empty. * @return int|bool Meta ID if the key didn't exist, true on successful update, - * false on failure. + * false on failure or if the value passed to the function + * is the same as the one that is already in the database. */ function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) { // Make sure meta is added to the post, not a revision. diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php index d8df47e5fd..d02aa9b9e4 100644 --- a/wp-includes/taxonomy.php +++ b/wp-includes/taxonomy.php @@ -1274,10 +1274,12 @@ function get_term_meta( $term_id, $key = '', $single = false ) { * @param string $meta_key Metadata key. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. * @param mixed $prev_value Optional. Previous value to check before updating. - * Default empty. + * If specified, only update existing metadata entries with + * this value. Otherwise, update all entries. Default empty. * @return int|bool|WP_Error Meta ID if the key didn't exist. true on successful update, - * false on failure. WP_Error when term_id is ambiguous - * between taxonomies. + * false on failure or if the value passed to the function + * is the same as the one that is already in the database. + * WP_Error when term_id is ambiguous between taxonomies. */ function update_term_meta( $term_id, $meta_key, $meta_value, $prev_value = '' ) { if ( wp_term_is_shared( $term_id ) ) { diff --git a/wp-includes/user.php b/wp-includes/user.php index 6d75e07c1e..63047c7219 100644 --- a/wp-includes/user.php +++ b/wp-includes/user.php @@ -853,9 +853,11 @@ function get_user_meta( $user_id, $key = '', $single = false ) { * @param string $meta_key Metadata key. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. * @param mixed $prev_value Optional. Previous value to check before updating. - * Default empty. + * If specified, only update existing metadata entries with + * this value. Otherwise, update all entries. Default empty. * @return int|bool Meta ID if the key didn't exist, true on successful update, - * false on failure. + * false on failure or if the value passed to the function + * is the same as the one that is already in the database. */ function update_user_meta( $user_id, $meta_key, $meta_value, $prev_value = '' ) { return update_metadata( 'user', $user_id, $meta_key, $meta_value, $prev_value ); diff --git a/wp-includes/version.php b/wp-includes/version.php index b6a9f70ae8..ffc03631d1 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -13,7 +13,7 @@ * * @global string $wp_version */ -$wp_version = '5.5-alpha-48213'; +$wp_version = '5.5-alpha-48214'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.