diff --git a/src/wp-includes/comment.php b/src/wp-includes/comment.php index 2762b77593308..00bda2615d930 100644 --- a/src/wp-includes/comment.php +++ b/src/wp-includes/comment.php @@ -432,7 +432,13 @@ function get_comment_count( $post_id = 0 ) { * * @param int $comment_id Comment ID. * @param string $meta_key Metadata name. - * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. + * @param mixed $meta_value Metadata value. Arrays and objects are stored as serialized data and + * will be returned as the same type when retrieved. Other data types will + * be stored as strings in the database: + * - false is stored and retrieved as an empty string ('') + * - true is stored and retrieved as '1' + * - numbers (both integer and float) are stored and retrieved as strings + * Must be serializable if non-scalar. * @param bool $unique Optional. Whether the same key should not be added. * Default false. * @return int|false Meta ID on success, false on failure. @@ -481,6 +487,11 @@ function delete_comment_meta( $comment_id, $meta_key, $meta_value = '' ) { * False for an invalid `$comment_id` (non-numeric, zero, or negative value). * An empty array if a valid but non-existing comment ID is passed and `$single` is false. * An empty string if a valid but non-existing comment ID is passed and `$single` is true. + * Note: Non-serialized values are returned as strings: + * - false values are returned as empty strings ('') + * - true values are returned as '1' + * - numbers are returned as strings + * Arrays and objects retain their original type. */ function get_comment_meta( $comment_id, $key = '', $single = false ) { return get_metadata( 'comment', $comment_id, $key, $single ); diff --git a/src/wp-includes/meta.php b/src/wp-includes/meta.php index 6f6dd928e0498..4d8c49bfd11dd 100644 --- a/src/wp-includes/meta.php +++ b/src/wp-includes/meta.php @@ -23,7 +23,13 @@ * 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 mixed $meta_value Metadata value. Must be serializable if non-scalar. + * @param mixed $meta_value Metadata value. Arrays and objects are stored as serialized data and + * will be returned as the same type when retrieved. Other data types will + * be stored as strings in the database: + * - false is stored and retrieved as an empty string ('') + * - true is stored and retrieved as '1' + * - numbers (both integer and float) are stored and retrieved as strings + * Must be serializable if non-scalar. * @param bool $unique Optional. Whether the specified metadata key should be unique for the object. * If true, and the object already has a value for the specified metadata key, * no change will be made. Default false. @@ -570,6 +576,11 @@ function delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $ * or if `$meta_type` is not specified. * An empty array if a valid but non-existing object ID is passed and `$single` is false. * An empty string if a valid but non-existing object ID is passed and `$single` is true. + * Note: Non-serialized values are returned as strings: + * - false values are returned as empty strings ('') + * - true values are returned as '1' + * - numbers (both integer and float) are returned as strings + * Arrays and objects retain their original type. */ function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) { $value = get_metadata_raw( $meta_type, $object_id, $meta_key, $single ); diff --git a/src/wp-includes/ms-site.php b/src/wp-includes/ms-site.php index b1d50940a245b..2a2b1474c5d61 100644 --- a/src/wp-includes/ms-site.php +++ b/src/wp-includes/ms-site.php @@ -1026,7 +1026,13 @@ function clean_blog_cache( $blog ) { * * @param int $site_id Site ID. * @param string $meta_key Metadata name. - * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. + * @param mixed $meta_value Metadata value. Arrays and objects are stored as serialized data and + * will be returned as the same type when retrieved. Other data types will + * be stored as strings in the database: + * - false is stored and retrieved as an empty string ('') + * - true is stored and retrieved as '1' + * - numbers (both integer and float) are stored and retrieved as strings + * Must be serializable if non-scalar. * @param bool $unique Optional. Whether the same key should not be added. * Default false. * @return int|false Meta ID on success, false on failure. @@ -1071,6 +1077,11 @@ function delete_site_meta( $site_id, $meta_key, $meta_value = '' ) { * False for an invalid `$site_id` (non-numeric, zero, or negative value). * An empty array if a valid but non-existing site ID is passed and `$single` is false. * An empty string if a valid but non-existing site ID is passed and `$single` is true. + * Note: Non-serialized values are returned as strings: + * - false values are returned as empty strings ('') + * - true values are returned as '1' + * - numbers (both integer and float) are returned as strings + * Arrays and objects retain their original type. */ function get_site_meta( $site_id, $key = '', $single = false ) { return get_metadata( 'blog', $site_id, $key, $single ); diff --git a/src/wp-includes/post.php b/src/wp-includes/post.php index 98b9092f16f1f..009287916d7bb 100644 --- a/src/wp-includes/post.php +++ b/src/wp-includes/post.php @@ -2558,7 +2558,13 @@ function get_posts( $args = null ) { * * @param int $post_id Post ID. * @param string $meta_key Metadata name. - * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. + * @param mixed $meta_value Metadata value. Arrays and objects are stored as serialized data and + * will be returned as the same type when retrieved. Other data types will + * be stored as strings in the database: + * - false is stored and retrieved as an empty string ('') + * - true is stored and retrieved as '1' + * - numbers (both integer and float) are stored and retrieved as strings + * Must be serializable if non-scalar. * @param bool $unique Optional. Whether the same key should not be added. * Default false. * @return int|false Meta ID on success, false on failure. @@ -2615,6 +2621,11 @@ function delete_post_meta( $post_id, $meta_key, $meta_value = '' ) { * False for an invalid `$post_id` (non-numeric, zero, or negative value). * An empty array if a valid but non-existing post ID is passed and `$single` is false. * An empty string if a valid but non-existing post ID is passed and `$single` is true. + * Note: Non-serialized values are returned as strings: + * - false values are returned as empty strings ('') + * - true values are returned as '1' + * - numbers (both integer and float) are returned as strings + * Arrays and objects retain their original type. */ function get_post_meta( $post_id, $key = '', $single = false ) { return get_metadata( 'post', $post_id, $key, $single ); diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php index bebf55ec79bfa..1af1b5a76b70d 100644 --- a/src/wp-includes/taxonomy.php +++ b/src/wp-includes/taxonomy.php @@ -1386,7 +1386,13 @@ function get_terms( $args = array(), $deprecated = '' ) { * * @param int $term_id Term ID. * @param string $meta_key Metadata name. - * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. + * @param mixed $meta_value Metadata value. Arrays and objects are stored as serialized data and + * will be returned as the same type when retrieved. Other data types will + * be stored as strings in the database: + * - false is stored and retrieved as an empty string ('') + * - true is stored and retrieved as '1' + * - numbers (both integer and float) are stored and retrieved as strings + * Must be serializable if non-scalar. * @param bool $unique Optional. Whether the same key should not be added. * Default false. * @return int|false|WP_Error Meta ID on success, false on failure. @@ -1432,6 +1438,11 @@ function delete_term_meta( $term_id, $meta_key, $meta_value = '' ) { * False for an invalid `$term_id` (non-numeric, zero, or negative value). * An empty array if a valid but non-existing term ID is passed and `$single` is false. * An empty string if a valid but non-existing term ID is passed and `$single` is true. + * Note: Non-serialized values are returned as strings: + * - false values are returned as empty strings ('') + * - true values are returned as '1' + * - numbers are returned as strings + * Arrays and objects retain their original type. */ function get_term_meta( $term_id, $key = '', $single = false ) { return get_metadata( 'term', $term_id, $key, $single ); diff --git a/src/wp-includes/user.php b/src/wp-includes/user.php index 635f82c5ed353..e4e6f5b652744 100644 --- a/src/wp-includes/user.php +++ b/src/wp-includes/user.php @@ -1151,7 +1151,13 @@ function is_user_member_of_blog( $user_id = 0, $blog_id = 0 ) { * * @param int $user_id User ID. * @param string $meta_key Metadata name. - * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. + * @param mixed $meta_value Metadata value. Arrays and objects are stored as serialized data and + * will be returned as the same type when retrieved. Other data types will + * be stored as strings in the database: + * - false is stored and retrieved as an empty string ('') + * - true is stored and retrieved as '1' + * - numbers (both integer and float) are stored and retrieved as strings + * Must be serializable if non-scalar. * @param bool $unique Optional. Whether the same key should not be added. * Default false. * @return int|false Meta ID on success, false on failure. @@ -1200,6 +1206,11 @@ function delete_user_meta( $user_id, $meta_key, $meta_value = '' ) { * False for an invalid `$user_id` (non-numeric, zero, or negative value). * An empty array if a valid but non-existing user ID is passed and `$single` is false. * An empty string if a valid but non-existing user ID is passed and `$single` is true. + * Note: Non-serialized values are returned as strings: + * - false values are returned as empty strings ('') + * - true values are returned as '1' + * - numbers (both integer and float) are returned as strings + * Arrays and objects retain their original type. */ function get_user_meta( $user_id, $key = '', $single = false ) { return get_metadata( 'user', $user_id, $key, $single );