From 133c4e2e509845e29ab7b25671bea2cc7cbf7f52 Mon Sep 17 00:00:00 2001
From: davidbaumwald <davidbaumwald@git.wordpress.org>
Date: Fri, 2 Apr 2021 15:49:05 +0000
Subject: [PATCH] Docs: Clarify return results for a non-existing ID in
metadata functions.
[48658] documented that various metadata functions return false for an invalid ID. However, that does not clarify what an invalid ID is: a non-numeric, zero, or negative value. This change adds the clarification in all relevant metadata function docblocks.
Props icopydoc, SergeyBiryukov, davidkryzaniak, audrasjb.
Fixes #51797.
Built from https://develop.svn.wordpress.org/trunk@50641
git-svn-id: http://core.svn.wordpress.org/trunk@50253 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
wp-includes/comment.php | 8 +++++---
wp-includes/meta.php | 36 ++++++++++++++++++++++--------------
wp-includes/ms-site.php | 8 +++++---
wp-includes/post.php | 8 +++++---
wp-includes/taxonomy.php | 8 +++++---
wp-includes/user.php | 8 +++++---
wp-includes/version.php | 2 +-
7 files changed, 48 insertions(+), 30 deletions(-)
diff --git a/wp-includes/comment.php b/wp-includes/comment.php
index 91672c1a13..5c4f2b5f3e 100644
--- a/wp-includes/comment.php
+++ b/wp-includes/comment.php
@@ -493,10 +493,12 @@ function delete_comment_meta( $comment_id, $meta_key, $meta_value = '' ) {
* @param string $key Optional. The meta key to retrieve. By default,
* returns data for all keys.
* @param bool $single Optional. Whether to return a single value.
- * This parameter has no effect if $key is not specified.
+ * This parameter has no effect if `$key` is not specified.
* Default false.
- * @return mixed An array if $single is false. The value of meta data field
- * if $single is true. False for an invalid $comment_id.
+ * @return mixed An array of values if `$single` is false.
+ * The value of meta data field if `$single` is true.
+ * False for an invalid `$comment_id` (non-numeric, zero, or negative value).
+ * An empty string if a valid but non-existing comment ID is passed.
*/
function get_comment_meta( $comment_id, $key = '', $single = false ) {
return get_metadata( 'comment', $comment_id, $key, $single );
diff --git a/wp-includes/meta.php b/wp-includes/meta.php
index 8bdb9d3ae5..40b2a74159 100644
--- a/wp-includes/meta.php
+++ b/wp-includes/meta.php
@@ -497,10 +497,13 @@ function delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $
* @param int $object_id ID of the object metadata is for.
* @param string $meta_key Optional. Metadata key. If not specified, retrieve all metadata for
* the specified object. Default empty.
- * @param bool $single Optional. If true, return only the first value of the specified meta_key.
- * This parameter has no effect if meta_key is not specified. Default false.
- * @return mixed Single metadata value, or array of values.
- * False if there's a problem with the parameters passed to the function.
+ * @param bool $single Optional. If true, return only the first value of the specified `$meta_key`.
+ * This parameter has no effect if `$meta_key` is not specified. Default false.
+ * @return mixed An array of values if `$single` is false.
+ * The value of the meta field if `$single` is true.
+ * False for an invalid `$object_id` (non-numeric, zero, or negative value),
+ * or if `$meta_type` is not specified.
+ * An empty string if a valid but non-existing object ID is passed.
*/
function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) {
$value = get_metadata_raw( $meta_type, $object_id, $meta_key, $single );
@@ -521,10 +524,13 @@ function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false )
* @param int $object_id ID of the object metadata is for.
* @param string $meta_key Optional. Metadata key. If not specified, retrieve all metadata for
* the specified object. Default empty.
- * @param bool $single Optional. If true, return only the first value of the specified meta_key.
- * This parameter has no effect if meta_key is not specified. Default false.
- * @return mixed Single metadata value, or array of values. Null if the value does not exist.
- * False if there's a problem with the parameters passed to the function.
+ * @param bool $single Optional. If true, return only the first value of the specified `$meta_key`.
+ * This parameter has no effect if `$meta_key` is not specified. Default false.
+ * @return mixed An array of values if `$single` is false.
+ * The value of the meta field if `$single` is true.
+ * False for an invalid `$object_id` (non-numeric, zero, or negative value),
+ * or if `$meta_type` is not specified.
+ * Null if the value does not exist.
*/
function get_metadata_raw( $meta_type, $object_id, $meta_key = '', $single = false ) {
if ( ! $meta_type || ! is_numeric( $object_id ) ) {
@@ -608,9 +614,10 @@ function get_metadata_raw( $meta_type, $object_id, $meta_key = '', $single = fal
* or any other object type with an associated meta table.
* @param int $object_id ID of the object metadata is for.
* @param string $meta_key Metadata key.
- * @param bool $single Optional. If true, return only the first value of the specified meta_key.
- * This parameter has no effect if meta_key is not specified. Default false.
- * @return mixed Single metadata value, or array of values.
+ * @param bool $single Optional. If true, return only the first value of the specified `$meta_key`.
+ * This parameter has no effect if `$meta_key` is not specified. Default false.
+ * @return mixed An array of default values if `$single` is false.
+ * The default value of the meta field if `$single` is true.
*/
function get_metadata_default( $meta_type, $object_id, $meta_key, $single = false ) {
if ( $single ) {
@@ -1401,11 +1408,12 @@ function register_meta( $object_type, $meta_key, $args, $deprecated = null ) {
* @param mixed $value Current value passed to filter.
* @param int $object_id ID of the object metadata is for.
* @param string $meta_key Metadata key.
- * @param bool $single If true, return only the first value of the specified meta_key.
- * This parameter has no effect if meta_key is not specified.
+ * @param bool $single If true, return only the first value of the specified `$meta_key`.
+ * This parameter has no effect if `$meta_key` is not specified.
* @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* or any other object type with an associated meta table.
- * @return mixed Single metadata default, or array of defaults.
+ * @return mixed An array of default values if `$single` is false.
+ * The default value of the meta field if `$single` is true.
*/
function filter_default_metadata( $value, $object_id, $meta_key, $single, $meta_type ) {
global $wp_meta_keys;
diff --git a/wp-includes/ms-site.php b/wp-includes/ms-site.php
index 61542c1755..9a5b2ad43a 100644
--- a/wp-includes/ms-site.php
+++ b/wp-includes/ms-site.php
@@ -1084,10 +1084,12 @@ function delete_site_meta( $site_id, $meta_key, $meta_value = '' ) {
* @param string $key Optional. The meta key to retrieve. By default,
* returns data for all keys. Default empty.
* @param bool $single Optional. Whether to return a single value.
- * This parameter has no effect if $key is not specified.
+ * This parameter has no effect if `$key` is not specified.
* Default false.
- * @return mixed An array if $single is false. The value of meta data field
- * if $single is true. False for an invalid $site_id.
+ * @return mixed An array of values if `$single` is false.
+ * The value of meta data field if `$single` is true.
+ * False for an invalid `$site_id` (non-numeric, zero, or negative value).
+ * An empty string if a valid but non-existing site ID is passed.
*/
function get_site_meta( $site_id, $key = '', $single = false ) {
return get_metadata( 'blog', $site_id, $key, $single );
diff --git a/wp-includes/post.php b/wp-includes/post.php
index f8ab2583ae..c04f9f78b3 100644
--- a/wp-includes/post.php
+++ b/wp-includes/post.php
@@ -2236,10 +2236,12 @@ function delete_post_meta( $post_id, $meta_key, $meta_value = '' ) {
* @param string $key Optional. The meta key to retrieve. By default,
* returns data for all keys. Default empty.
* @param bool $single Optional. Whether to return a single value.
- * This parameter has no effect if $key is not specified.
+ * This parameter has no effect if `$key` is not specified.
* Default false.
- * @return mixed An array if $single is false. The value of the meta field
- * if $single is true. False for an invalid $post_id.
+ * @return mixed An array of values if `$single` is false.
+ * The value of the meta field if `$single` is true.
+ * False for an invalid `$post_id` (non-numeric, zero, or negative value).
+ * An empty string if a valid but non-existing post ID is passed.
*/
function get_post_meta( $post_id, $key = '', $single = false ) {
return get_metadata( 'post', $post_id, $key, $single );
diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php
index d9dd34ccf5..94d894e442 100644
--- a/wp-includes/taxonomy.php
+++ b/wp-includes/taxonomy.php
@@ -1324,10 +1324,12 @@ function delete_term_meta( $term_id, $meta_key, $meta_value = '' ) {
* @param string $key Optional. The meta key to retrieve. By default,
* returns data for all keys. Default empty.
* @param bool $single Optional. Whether to return a single value.
- * This parameter has no effect if $key is not specified.
+ * This parameter has no effect if `$key` is not specified.
* Default false.
- * @return mixed An array if $single is false. The value of the meta field
- * if $single is true. False for an invalid $term_id.
+ * @return mixed An array of values if `$single` is false.
+ * The value of the meta field if `$single` is true.
+ * False for an invalid `$term_id` (non-numeric, zero, or negative value).
+ * An empty string if a valid but non-existing term ID is passed.
*/
function get_term_meta( $term_id, $key = '', $single = false ) {
return get_metadata( 'term', $term_id, $key, $single );
diff --git a/wp-includes/user.php b/wp-includes/user.php
index 7aada19c9c..048bb4c511 100644
--- a/wp-includes/user.php
+++ b/wp-includes/user.php
@@ -1008,10 +1008,12 @@ function delete_user_meta( $user_id, $meta_key, $meta_value = '' ) {
* @param string $key Optional. The meta key to retrieve. By default,
* returns data for all keys.
* @param bool $single Optional. Whether to return a single value.
- * This parameter has no effect if $key is not specified.
+ * This parameter has no effect if `$key` is not specified.
* Default false.
- * @return mixed An array if $single is false. The value of meta data field
- * if $single is true. False for an invalid $user_id.
+ * @return mixed An array of values if `$single` is false.
+ * The value of meta data field if `$single` is true.
+ * False for an invalid `$user_id` (non-numeric, zero, or negative value).
+ * An empty string if a valid but non-existing user ID is passed.
*/
function get_user_meta( $user_id, $key = '', $single = false ) {
return get_metadata( 'user', $user_id, $key, $single );
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 1cdf4c2251..c621760e3e 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -13,7 +13,7 @@
*
* @global string $wp_version
*/
-$wp_version = '5.8-alpha-50634';
+$wp_version = '5.8-alpha-50641';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.