Upstream
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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
This commit is contained in:
Sergey Biryukov 2020-06-29 21:22:09 +00:00
parent 7d19adab35
commit 347e831768
7 changed files with 33 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
wp-includes/comment.php
View File

@ -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 );

17
wp-includes/meta.php
View File

@ -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 ) {

6
wp-includes/ms-site.php
View File

@ -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 );

6
wp-includes/post.php
View File

@ -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.

8
wp-includes/taxonomy.php
View File

@ -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 ) ) {

6
wp-includes/user.php
View File

@ -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 );

2
wp-includes/version.php
View File

@ -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.