Make WordPress Core

Changeset 59657


Ignore:
Timestamp:
01/17/2025 12:10:08 AM (4 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.

Location:
trunk/src/wp-includes
Files:
6 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/comment.php

    r59556 r59657  
    433433 * @param int    $comment_id Comment ID.
    434434 * @param string $meta_key   Metadata name.
    435  * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
     435 * @param mixed  $meta_value Metadata value. Arrays and objects are stored as serialized data and
     436 *                           will be returned as the same type when retrieved. Other data types will
     437 *                           be stored as strings in the database:
     438 *                           - false is stored and retrieved as an empty string ('')
     439 *                           - true is stored and retrieved as '1'
     440 *                           - numbers (both integer and float) are stored and retrieved as strings
     441 *                           Must be serializable if non-scalar.
    436442 * @param bool   $unique     Optional. Whether the same key should not be added.
    437443 *                           Default false.
     
    482488 *               An empty array if a valid but non-existing comment ID is passed and `$single` is false.
    483489 *               An empty string if a valid but non-existing comment ID is passed and `$single` is true.
     490 *               Note: Non-serialized values are returned as strings:
     491 *               - false values are returned as empty strings ('')
     492 *               - true values are returned as '1'
     493 *               - numbers are returned as strings
     494 *               Arrays and objects retain their original type.
    484495 */
    485496function get_comment_meta( $comment_id, $key = '', $single = false ) {
  • trunk/src/wp-includes/meta.php

    r59023 r59657  
    2424 * @param int    $object_id  ID of the object metadata is for.
    2525 * @param string $meta_key   Metadata key.
    26  * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
     26 * @param mixed  $meta_value Metadata value. Arrays and objects are stored as serialized data and
     27 *                           will be returned as the same type when retrieved. Other data types will
     28 *                           be stored as strings in the database:
     29 *                           - false is stored and retrieved as an empty string ('')
     30 *                           - true is stored and retrieved as '1'
     31 *                           - numbers (both integer and float) are stored and retrieved as strings
     32 *                           Must be serializable if non-scalar.
    2733 * @param bool   $unique     Optional. Whether the specified metadata key should be unique for the object.
    2834 *                           If true, and the object already has a value for the specified metadata key,
     
    571577 *               An empty array if a valid but non-existing object ID is passed and `$single` is false.
    572578 *               An empty string if a valid but non-existing object ID is passed and `$single` is true.
     579 *               Note: Non-serialized values are returned as strings:
     580 *               - false values are returned as empty strings ('')
     581 *               - true values are returned as '1'
     582 *               - numbers (both integer and float) are returned as strings
     583 *               Arrays and objects retain their original type.
    573584 */
    574585function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) {
  • trunk/src/wp-includes/ms-site.php

    r59009 r59657  
    10271027 * @param int    $site_id    Site ID.
    10281028 * @param string $meta_key   Metadata name.
    1029  * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
     1029 * @param mixed  $meta_value Metadata value. Arrays and objects are stored as serialized data and
     1030 *                           will be returned as the same type when retrieved. Other data types will
     1031 *                           be stored as strings in the database:
     1032 *                           - false is stored and retrieved as an empty string ('')
     1033 *                           - true is stored and retrieved as '1'
     1034 *                           - numbers (both integer and float) are stored and retrieved as strings
     1035 *                           Must be serializable if non-scalar.
    10301036 * @param bool   $unique     Optional. Whether the same key should not be added.
    10311037 *                           Default false.
     
    10721078 *               An empty array if a valid but non-existing site ID is passed and `$single` is false.
    10731079 *               An empty string if a valid but non-existing site ID is passed and `$single` is true.
     1080 *               Note: Non-serialized values are returned as strings:
     1081 *               - false values are returned as empty strings ('')
     1082 *               - true values are returned as '1'
     1083 *               - numbers (both integer and float) are returned as strings
     1084 *               Arrays and objects retain their original type.
    10741085 */
    10751086function get_site_meta( $site_id, $key = '', $single = false ) {
  • trunk/src/wp-includes/post.php

    r59602 r59657  
    25592559 * @param int    $post_id    Post ID.
    25602560 * @param string $meta_key   Metadata name.
    2561  * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
     2561 * @param mixed  $meta_value Metadata value. Arrays and objects are stored as serialized data and
     2562 *                           will be returned as the same type when retrieved. Other data types will
     2563 *                           be stored as strings in the database:
     2564 *                           - false is stored and retrieved as an empty string ('')
     2565 *                           - true is stored and retrieved as '1'
     2566 *                           - numbers (both integer and float) are stored and retrieved as strings
     2567 *                           Must be serializable if non-scalar.
    25622568 * @param bool   $unique     Optional. Whether the same key should not be added.
    25632569 *                           Default false.
     
    26162622 *               An empty array if a valid but non-existing post ID is passed and `$single` is false.
    26172623 *               An empty string if a valid but non-existing post ID is passed and `$single` is true.
     2624 *               Note: Non-serialized values are returned as strings:
     2625 *               - false values are returned as empty strings ('')
     2626 *               - true values are returned as '1'
     2627 *               - numbers (both integer and float) are returned as strings
     2628 *               Arrays and objects retain their original type.
    26182629 */
    26192630function get_post_meta( $post_id, $key = '', $single = false ) {
  • trunk/src/wp-includes/taxonomy.php

    r58962 r59657  
    13871387 * @param int    $term_id    Term ID.
    13881388 * @param string $meta_key   Metadata name.
    1389  * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
     1389 * @param mixed  $meta_value Metadata value. Arrays and objects are stored as serialized data and
     1390 *                           will be returned as the same type when retrieved. Other data types will
     1391 *                           be stored as strings in the database:
     1392 *                           - false is stored and retrieved as an empty string ('')
     1393 *                           - true is stored and retrieved as '1'
     1394 *                           - numbers (both integer and float) are stored and retrieved as strings
     1395 *                           Must be serializable if non-scalar.
    13901396 * @param bool   $unique     Optional. Whether the same key should not be added.
    13911397 *                           Default false.
     
    14331439 *               An empty array if a valid but non-existing term ID is passed and `$single` is false.
    14341440 *               An empty string if a valid but non-existing term ID is passed and `$single` is true.
     1441 *               Note: Non-serialized values are returned as strings:
     1442 *               - false values are returned as empty strings ('')
     1443 *               - true values are returned as '1'
     1444 *               - numbers are returned as strings
     1445 *               Arrays and objects retain their original type.
    14351446 */
    14361447function get_term_meta( $term_id, $key = '', $single = false ) {
  • trunk/src/wp-includes/user.php

    r59633 r59657  
    11521152 * @param int    $user_id    User ID.
    11531153 * @param string $meta_key   Metadata name.
    1154  * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
     1154 * @param mixed  $meta_value Metadata value. Arrays and objects are stored as serialized data and
     1155 *                           will be returned as the same type when retrieved. Other data types will
     1156 *                           be stored as strings in the database:
     1157 *                           - false is stored and retrieved as an empty string ('')
     1158 *                           - true is stored and retrieved as '1'
     1159 *                           - numbers (both integer and float) are stored and retrieved as strings
     1160 *                           Must be serializable if non-scalar.
    11551161 * @param bool   $unique     Optional. Whether the same key should not be added.
    11561162 *                           Default false.
     
    12011207 *               An empty array if a valid but non-existing user ID is passed and `$single` is false.
    12021208 *               An empty string if a valid but non-existing user ID is passed and `$single` is true.
     1209 *               Note: Non-serialized values are returned as strings:
     1210 *               - false values are returned as empty strings ('')
     1211 *               - true values are returned as '1'
     1212 *               - numbers (both integer and float) are returned as strings
     1213 *               Arrays and objects retain their original type.
    12031214 */
    12041215function get_user_meta( $user_id, $key = '', $single = false ) {
Note: See TracChangeset for help on using the changeset viewer.