WordPress.org

Make WordPress Core

Changeset 50641


Ignore:
Timestamp:
04/02/2021 03:47:34 PM (6 months ago)
Author:
davidbaumwald
Message:

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.

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

Legend:

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

    r50558 r50641  
    494494 *                           returns data for all keys.
    495495 * @param bool   $single     Optional. Whether to return a single value.
    496  *                           This parameter has no effect if $key is not specified.
     496 *                           This parameter has no effect if `$key` is not specified.
    497497 *                           Default false.
    498  * @return mixed An array if $single is false. The value of meta data field
    499  *               if $single is true. False for an invalid $comment_id.
     498 * @return mixed An array of values if `$single` is false.
     499 *               The value of meta data field if `$single` is true.
     500 *               False for an invalid `$comment_id` (non-numeric, zero, or negative value).
     501 *               An empty string if a valid but non-existing comment ID is passed.
    500502 */
    501503function get_comment_meta( $comment_id, $key = '', $single = false ) {
  • trunk/src/wp-includes/meta.php

    r49927 r50641  
    498498 * @param string $meta_key  Optional. Metadata key. If not specified, retrieve all metadata for
    499499 *                          the specified object. Default empty.
    500  * @param bool   $single    Optional. If true, return only the first value of the specified meta_key.
    501  *                          This parameter has no effect if meta_key is not specified. Default false.
    502  * @return mixed Single metadata value, or array of values.
    503  *               False if there's a problem with the parameters passed to the function.
     500 * @param bool   $single    Optional. If true, return only the first value of the specified `$meta_key`.
     501 *                          This parameter has no effect if `$meta_key` is not specified. Default false.
     502 * @return mixed An array of values if `$single` is false.
     503 *               The value of the meta field if `$single` is true.
     504 *               False for an invalid `$object_id` (non-numeric, zero, or negative value),
     505 *               or if `$meta_type` is not specified.
     506 *               An empty string if a valid but non-existing object ID is passed.
    504507 */
    505508function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) {
     
    522525 * @param string $meta_key  Optional. Metadata key. If not specified, retrieve all metadata for
    523526 *                          the specified object. Default empty.
    524  * @param bool   $single    Optional. If true, return only the first value of the specified meta_key.
    525  *                          This parameter has no effect if meta_key is not specified. Default false.
    526  * @return mixed Single metadata value, or array of values. Null if the value does not exist.
    527  *               False if there's a problem with the parameters passed to the function.
     527 * @param bool   $single    Optional. If true, return only the first value of the specified `$meta_key`.
     528 *                          This parameter has no effect if `$meta_key` is not specified. Default false.
     529 * @return mixed An array of values if `$single` is false.
     530 *               The value of the meta field if `$single` is true.
     531 *               False for an invalid `$object_id` (non-numeric, zero, or negative value),
     532 *               or if `$meta_type` is not specified.
     533 *               Null if the value does not exist.
    528534 */
    529535function get_metadata_raw( $meta_type, $object_id, $meta_key = '', $single = false ) {
     
    609615 * @param int    $object_id ID of the object metadata is for.
    610616 * @param string $meta_key  Metadata key.
    611  * @param bool   $single    Optional. If true, return only the first value of the specified meta_key.
    612  *                          This parameter has no effect if meta_key is not specified. Default false.
    613  * @return mixed Single metadata value, or array of values.
     617 * @param bool   $single    Optional. If true, return only the first value of the specified `$meta_key`.
     618 *                          This parameter has no effect if `$meta_key` is not specified. Default false.
     619 * @return mixed An array of default values if `$single` is false.
     620 *               The default value of the meta field if `$single` is true.
    614621 */
    615622function get_metadata_default( $meta_type, $object_id, $meta_key, $single = false ) {
     
    14021409 * @param int    $object_id ID of the object metadata is for.
    14031410 * @param string $meta_key  Metadata key.
    1404  * @param bool   $single    If true, return only the first value of the specified meta_key.
    1405  *                          This parameter has no effect if meta_key is not specified.
     1411 * @param bool   $single    If true, return only the first value of the specified `$meta_key`.
     1412 *                          This parameter has no effect if `$meta_key` is not specified.
    14061413 * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
    14071414 *                          or any other object type with an associated meta table.
    1408  * @return mixed Single metadata default, or array of defaults.
     1415 * @return mixed An array of default values if `$single` is false.
     1416 *               The default value of the meta field if `$single` is true.
    14091417 */
    14101418function filter_default_metadata( $value, $object_id, $meta_key, $single, $meta_type ) {
  • trunk/src/wp-includes/ms-site.php

    r49927 r50641  
    10851085 *                        returns data for all keys. Default empty.
    10861086 * @param bool   $single  Optional. Whether to return a single value.
    1087  *                        This parameter has no effect if $key is not specified.
     1087 *                        This parameter has no effect if `$key` is not specified.
    10881088 *                        Default false.
    1089  * @return mixed An array if $single is false. The value of meta data field
    1090  *               if $single is true. False for an invalid $site_id.
     1089 * @return mixed An array of values if `$single` is false.
     1090 *               The value of meta data field if `$single` is true.
     1091 *               False for an invalid `$site_id` (non-numeric, zero, or negative value).
     1092 *               An empty string if a valid but non-existing site ID is passed.
    10911093 */
    10921094function get_site_meta( $site_id, $key = '', $single = false ) {
  • trunk/src/wp-includes/post.php

    r50621 r50641  
    22372237 *                        returns data for all keys. Default empty.
    22382238 * @param bool   $single  Optional. Whether to return a single value.
    2239  *                        This parameter has no effect if $key is not specified.
     2239 *                        This parameter has no effect if `$key` is not specified.
    22402240 *                        Default false.
    2241  * @return mixed An array if $single is false. The value of the meta field
    2242  *               if $single is true. False for an invalid $post_id.
     2241 * @return mixed An array of values if `$single` is false.
     2242 *               The value of the meta field if `$single` is true.
     2243 *               False for an invalid `$post_id` (non-numeric, zero, or negative value).
     2244 *               An empty string if a valid but non-existing post ID is passed.
    22432245 */
    22442246function get_post_meta( $post_id, $key = '', $single = false ) {
  • trunk/src/wp-includes/taxonomy.php

    r50565 r50641  
    13251325 *                        returns data for all keys. Default empty.
    13261326 * @param bool   $single  Optional. Whether to return a single value.
    1327  *                        This parameter has no effect if $key is not specified.
     1327 *                        This parameter has no effect if `$key` is not specified.
    13281328 *                        Default false.
    1329  * @return mixed An array if $single is false. The value of the meta field
    1330  *               if $single is true. False for an invalid $term_id.
     1329 * @return mixed An array of values if `$single` is false.
     1330 *               The value of the meta field if `$single` is true.
     1331 *               False for an invalid `$term_id` (non-numeric, zero, or negative value).
     1332 *               An empty string if a valid but non-existing term ID is passed.
    13311333 */
    13321334function get_term_meta( $term_id, $key = '', $single = false ) {
  • trunk/src/wp-includes/user.php

    r50589 r50641  
    10091009 *                        returns data for all keys.
    10101010 * @param bool   $single  Optional. Whether to return a single value.
    1011  *                        This parameter has no effect if $key is not specified.
     1011 *                        This parameter has no effect if `$key` is not specified.
    10121012 *                        Default false.
    1013  * @return mixed An array if $single is false. The value of meta data field
    1014  *               if $single is true. False for an invalid $user_id.
     1013 * @return mixed An array of values if `$single` is false.
     1014 *               The value of meta data field if `$single` is true.
     1015 *               False for an invalid `$user_id` (non-numeric, zero, or negative value).
     1016 *               An empty string if a valid but non-existing user ID is passed.
    10151017 */
    10161018function get_user_meta( $user_id, $key = '', $single = false ) {
Note: See TracChangeset for help on using the changeset viewer.