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

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
This commit is contained in:
davidbaumwald 2021-04-02 15:49:05 +00:00
parent 526dfa8b12
commit 133c4e2e50
7 changed files with 48 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
wp-includes/comment.php
View File

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

36
wp-includes/meta.php
View File

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

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

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

8
wp-includes/post.php
View File

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

8
wp-includes/taxonomy.php
View File

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

8
wp-includes/user.php
View File

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

2
wp-includes/version.php
View File

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