Changeset 59657 for trunk/src/wp-includes/user.php

Timestamp:

01/17/2025 12:10:08 AM (5 months ago)

Author:

peterwilsoncc

Message:

Options/Meta APIs: Document type juggling of meta data.

Document that unserialised data types are stored as strings in the database and returned as such by the meta data functions. For example, setting meta data to the integer value 1 will be returned as "1" when subsequently queried via get_metadata() and the related functions.

Props sukhendu2002, azaozz, jrf, rodrigosprimo.
Fixes ticket:61950.

File:

• trunk/src/wp-includes/user.php (modified) (2 diffs)

trunk/src/wp-includes/user.php

@@ -1152 +1152 @@
  * @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.
@@ -1201 +1207 @@
  *               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 ) {