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:
parent
7d19adab35
commit
347e831768
@ -517,9 +517,11 @@ function get_comment_meta( $comment_id, $key = '', $single = false ) {
|
|||||||
* @param string $meta_key Metadata key.
|
* @param string $meta_key Metadata key.
|
||||||
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
|
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
|
||||||
* @param mixed $prev_value Optional. Previous value to check before updating.
|
* @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,
|
* @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 = '' ) {
|
function update_comment_meta( $comment_id, $meta_key, $meta_value, $prev_value = '' ) {
|
||||||
return update_metadata( 'comment', $comment_id, $meta_key, $meta_value, $prev_value );
|
return update_metadata( 'comment', $comment_id, $meta_key, $meta_value, $prev_value );
|
||||||
|
@ -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 int $object_id ID of the object metadata is for.
|
||||||
* @param string $meta_key Metadata key.
|
* @param string $meta_key Metadata key.
|
||||||
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
|
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
|
||||||
* @param mixed $prev_value Optional. If specified, only update existing metadata entries
|
* @param mixed $prev_value Optional. Previous value to check before updating.
|
||||||
* with this value. Otherwise, update all entries. Default empty.
|
* If specified, only update existing metadata entries with
|
||||||
* @return int|bool The new meta field ID if a field with the given key didn't exist and was
|
* this value. Otherwise, update all entries. Default empty.
|
||||||
* therefore added, true on successful update, false on failure.
|
* @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 = '' ) {
|
function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_value = '' ) {
|
||||||
global $wpdb;
|
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 int $object_id ID of the object metadata is for.
|
||||||
* @param string $meta_key Metadata key.
|
* @param string $meta_key Metadata key.
|
||||||
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
|
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
|
||||||
* @param mixed $prev_value Optional. If specified, only update existing metadata entries
|
* @param mixed $prev_value Optional. Previous value to check before updating.
|
||||||
* with this value. Otherwise, update all entries.
|
* 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 );
|
$check = apply_filters( "update_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $prev_value );
|
||||||
if ( null !== $check ) {
|
if ( null !== $check ) {
|
||||||
|
@ -1107,9 +1107,11 @@ function get_site_meta( $site_id, $key = '', $single = false ) {
|
|||||||
* @param string $meta_key Metadata key.
|
* @param string $meta_key Metadata key.
|
||||||
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
|
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
|
||||||
* @param mixed $prev_value Optional. Previous value to check before updating.
|
* @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,
|
* @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 = '' ) {
|
function update_site_meta( $site_id, $meta_key, $meta_value, $prev_value = '' ) {
|
||||||
return update_metadata( 'blog', $site_id, $meta_key, $meta_value, $prev_value );
|
return update_metadata( 'blog', $site_id, $meta_key, $meta_value, $prev_value );
|
||||||
|
@ -2140,9 +2140,11 @@ function get_post_meta( $post_id, $key = '', $single = false ) {
|
|||||||
* @param string $meta_key Metadata key.
|
* @param string $meta_key Metadata key.
|
||||||
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
|
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
|
||||||
* @param mixed $prev_value Optional. Previous value to check before updating.
|
* @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,
|
* @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 = '' ) {
|
function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) {
|
||||||
// Make sure meta is added to the post, not a revision.
|
// Make sure meta is added to the post, not a revision.
|
||||||
|
@ -1274,10 +1274,12 @@ function get_term_meta( $term_id, $key = '', $single = false ) {
|
|||||||
* @param string $meta_key Metadata key.
|
* @param string $meta_key Metadata key.
|
||||||
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
|
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
|
||||||
* @param mixed $prev_value Optional. Previous value to check before updating.
|
* @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,
|
* @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
|
* false on failure or if the value passed to the function
|
||||||
* between taxonomies.
|
* 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 = '' ) {
|
function update_term_meta( $term_id, $meta_key, $meta_value, $prev_value = '' ) {
|
||||||
if ( wp_term_is_shared( $term_id ) ) {
|
if ( wp_term_is_shared( $term_id ) ) {
|
||||||
|
@ -853,9 +853,11 @@ function get_user_meta( $user_id, $key = '', $single = false ) {
|
|||||||
* @param string $meta_key Metadata key.
|
* @param string $meta_key Metadata key.
|
||||||
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
|
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
|
||||||
* @param mixed $prev_value Optional. Previous value to check before updating.
|
* @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,
|
* @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 = '' ) {
|
function update_user_meta( $user_id, $meta_key, $meta_value, $prev_value = '' ) {
|
||||||
return update_metadata( 'user', $user_id, $meta_key, $meta_value, $prev_value );
|
return update_metadata( 'user', $user_id, $meta_key, $meta_value, $prev_value );
|
||||||
|
@ -13,7 +13,7 @@
|
|||||||
*
|
*
|
||||||
* @global string $wp_version
|
* @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.
|
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.
|
||||||
|
Loading…
Reference in New Issue
Block a user