Make WordPress Core

Changeset 48411


Ignore:
Timestamp:
07/09/2020 11:24:43 AM (4 years ago)
Author:
SergeyBiryukov
Message:

Docs: Synchronize and correct documentation for various metadata functions and filters.

Follow-up to [47390], [47611], [48192], [48402].

See #49572, #43941, #45464.

Location:
trunk
Files:
3 edited

Legend:

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

    r48408 r48411  
    5757     * Short-circuits adding metadata of a specific type.
    5858     *
    59      * The dynamic portion of the hook, `$meta_type`, refers to the meta
    60      * object type (comment, post, term, or user). Returning a non-null value
    61      * will effectively short-circuit the function.
     59     * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     60     * (post, comment, term, user, or any other type with an associated meta table).
     61     * Returning a non-null value will effectively short-circuit the function.
    6262     *
    6363     * @since 3.1.0
     
    9090     * Fires immediately before meta of a specific type is added.
    9191     *
    92      * The dynamic portion of the hook, `$meta_type`, refers to the meta
    93      * object type (comment, post, term, or user).
     92     * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     93     * (post, comment, term, user, or any other type with an associated meta table).
    9494     *
    9595     * @since 3.1.0
     
    121121     * Fires immediately after meta of a specific type is added.
    122122     *
    123      * The dynamic portion of the hook, `$meta_type`, refers to the meta
    124      * object type (comment, post, term, or user).
     123     * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     124     * (post, comment, term, user, or any other type with an associated meta table).
    125125     *
    126126     * @since 2.9.0
     
    190190     * Short-circuits updating metadata of a specific type.
    191191     *
    192      * The dynamic portion of the hook, `$meta_type`, refers to the meta
    193      * object type (comment, post, term, or user). Returning a non-null value
    194      * will effectively short-circuit the function.
     192     * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     193     * (post, comment, term, user, or any other type with an associated meta table).
     194     * Returning a non-null value will effectively short-circuit the function.
    195195     *
    196196     * @since 3.1.0
     
    242242         * Fires immediately before updating metadata of a specific type.
    243243         *
    244          * The dynamic portion of the hook, `$meta_type`, refers to the meta
    245          * object type (comment, post, term, or user).
     244         * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     245         * (post, comment, term, user, or any other type with an associated meta table).
    246246         *
    247247         * @since 2.9.0
     
    281281         * Fires immediately after updating metadata of a specific type.
    282282         *
    283          * The dynamic portion of the hook, `$meta_type`, refers to the meta
    284          * object type (comment, post, term, or user).
     283         * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     284         * (post, comment, term, user, or any other type with an associated meta table).
    285285         *
    286286         * @since 2.9.0
     
    361361     * Short-circuits deleting metadata of a specific type.
    362362     *
    363      * The dynamic portion of the hook, `$meta_type`, refers to the meta
    364      * object type (comment, post, term, or user). Returning a non-null value
    365      * will effectively short-circuit the function.
     363     * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     364     * (post, comment, term, user, or any other type with an associated meta table).
     365     * Returning a non-null value will effectively short-circuit the function.
    366366     *
    367367     * @since 3.1.0
     
    409409     * Fires immediately before deleting metadata of a specific type.
    410410     *
    411      * The dynamic portion of the hook, `$meta_type`, refers to the meta
    412      * object type (comment, post, term, or user).
     411     * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     412     * (post, comment, term, user, or any other type with an associated meta table).
    413413     *
    414414     * @since 3.1.0
     
    452452     * Fires immediately after deleting metadata of a specific type.
    453453     *
    454      * The dynamic portion of the hook name, `$meta_type`, refers to the meta
    455      * object type (comment, post, term, or user).
     454     * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     455     * (post, comment, term, user, or any other type with an associated meta table).
    456456     *
    457457     * @since 2.9.0
     
    482482 * Retrieves the value of a metadata field for the specified object type and ID.
    483483 *
    484  * If the meta field exists, a single value is returned if `$single` is true, or an array of values if it's false.
    485  * If the meta field does not exist, an empty string is returned if `$single` is true, or an empty array if it's false.
    486  * If there's a problem with the parameters passed to the function, boolean `false` is returned.
    487  *
    488  * @since 5.5.0
     484 * If the meta field exists, a single value is returned if `$single` is true,
     485 * or an array of values if it's false.
     486 *
     487 * If the meta field does not exist, the result depends on get_metadata_default().
     488 * By default, an empty string is returned if `$single` is true, or an empty array if it's false.
     489 *
     490 * @since 2.9.0
     491 *
     492 * @see get_metadata_raw()
     493 * @see get_metadata_default()
    489494 *
    490495 * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
     
    495500 * @param bool   $single    Optional. If true, return only the first value of the specified meta_key.
    496501 *                          This parameter has no effect if meta_key is not specified. Default false.
    497  * @return mixed The metadata value or array of values. See description above for further details.
     502 * @return mixed Single metadata value, or array of values.
     503 *               False if there's a problem with the parameters passed to the function.
     504 */
     505function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) {
     506    $value = get_metadata_raw( $meta_type, $object_id, $meta_key, $single );
     507    if ( ! is_null( $value ) ) {
     508        return $value;
     509    }
     510
     511    return get_metadata_default( $meta_type, $meta_key, $single, $object_id );
     512}
     513
     514/**
     515 * Retrieves raw metadata value for the specified object.
     516 *
     517 * @since 5.5.0
     518 *
     519 * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
     520 *                          or any other object type with an associated meta table.
     521 * @param int    $object_id ID of the object metadata is for.
     522 * @param string $meta_key  Optional. Metadata key. If not specified, retrieve all metadata for
     523 *                          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.
    498528 */
    499529function get_metadata_raw( $meta_type, $object_id, $meta_key = '', $single = false ) {
     
    510540     * Short-circuits the return value of a meta field.
    511541     *
    512      * The dynamic portion of the hook name, `$meta_type`, refers to the
    513      * object type (comment, post, term, or user). Returning a non-null value
    514      * will short-circuit the return value.
     542     * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     543     * (post, comment, term, user, or any other type with an associated meta table).
     544     * Returning a non-null value will effectively short-circuit the function.
    515545     *
    516546     * @since 3.1.0
     
    520550     * @param int    $object_id ID of the object metadata is for.
    521551     * @param string $meta_key  Metadata key.
    522      * @param bool   $single    Whether to return only the first value of the specified $meta_key.
     552     * @param bool   $single    Whether to return only the first value of the specified `$meta_key`.
    523553     */
    524554    $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, $single );
     
    558588
    559589/**
    560  * Retrieves raw metadata for the specified object.
    561  *
    562  * @since 2.9.0
    563  * @uses get_metadata_raw()
     590 * Retrieves default metadata value for the specified object.
     591 *
     592 * By default, an empty string is returned if `$single` is true, or an empty array if it's false.
     593 *
     594 * @since 5.5.0
    564595 *
    565596 * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
    566597 *                          or any other object type with an associated meta table.
    567  * @param int    $object_id ID of the object metadata is for.
    568  * @param string $meta_key  Optional. Metadata key. If not specified, retrieve all metadata for
    569  *                          the specified object. Default empty.
     598 * @param string $meta_key  Metadata key.
    570599 * @param bool   $single    Optional. If true, return only the first value of the specified meta_key.
    571600 *                          This parameter has no effect if meta_key is not specified. Default false.
    572  * @return mixed Single metadata value, or array of values
    573  */
    574 function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) {
    575     $value = get_metadata_raw( $meta_type, $object_id, $meta_key, $single );
    576     if ( ! is_null( $value ) ) {
    577         return $value;
    578     }
    579 
    580     return get_metadata_default( $meta_type, $meta_key, $single, $object_id );
    581 }
    582 
    583 /**
    584  * Retrieve metadata data default for the specified object.
    585  *
    586  * @since 5.5.0
    587  *
    588  * @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
    589  * @param string $meta_key  Optional. Metadata key. If not specified, retrieve all metadata for
    590  *                          the specified object.
    591  * @param bool   $single    Optional, default is false.
    592  *                          If true, return only the first value of the specified meta_key.
    593  *                          This parameter has no effect if meta_key is not specified.
    594  * @param int    $object_id Optional, default is 0.
    595  *                          ID of the object metadata is for
    596  * @return mixed Single metadata value, or array of values
     601 * @param int    $object_id Optional. ID of the object metadata is for. Default 0.
     602 * @return mixed Single metadata value, or array of values.
    597603 */
    598604function get_metadata_default( $meta_type, $meta_key, $single = false, $object_id = 0 ) {
     
    604610
    605611    /**
    606      * Filter the default value a specified object.
     612     * Filter the default value for a specified object.
     613     *
     614     * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     615     * (post, comment, term, user, or any other type with an associated meta table).
    607616     *
    608617     * @since 5.5.0
    609618     *
    610      * @param array|string      $value     The value should return - a single metadata value,
    611      *                                     or an array of values.
    612      * @param string            $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
    613      * @param string            $meta_key  Meta key.
    614      * @param bool              $single    Whether to return only the first value of the specified $meta_key.
    615      * @param int               $object_id Object ID.
     619     * @param mixed  $value     The value to return, either a single metadata value or an array
     620     *                          of values depending on the value of `$single`.
     621     * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
     622     *                          or any other object type with an associated meta table.
     623     * @param string $meta_key  Metadata key.
     624     * @param bool   $single    Whether to return only the first value of the specified `$meta_key`.
     625     * @param int    $object_id ID of the object metadata is for.
    616626     */
    617627    $value = apply_filters( "default_{$meta_type}_metadata", $value, $meta_type, $meta_key, $single, $object_id );
     
    705715    }
    706716
    707     $id_column = ( 'user' === $meta_type ) ? 'umeta_id' : 'meta_id';
    708 
    709717    /**
    710718     * Short-circuits the return value when fetching a meta field by meta ID.
    711719     *
    712      * The dynamic portion of the hook name, `$meta_type`, refers to the
    713      * object type (comment, post, term, or user). Returning a non-null value
    714      * will short-circuit the return value.
     720     * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     721     * (post, comment, term, user, or any other type with an associated meta table).
     722     * Returning a non-null value will effectively short-circuit the function.
    715723     *
    716724     * @since 5.0.0
     
    724732    }
    725733
     734    $id_column = ( 'user' === $meta_type ) ? 'umeta_id' : 'meta_id';
     735
    726736    $meta = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $table WHERE $id_column = %d", $meta_id ) );
    727737
     
    775785     * Short-circuits updating metadata of a specific type by meta ID.
    776786     *
    777      * The dynamic portion of the hook, `$meta_type`, refers to the meta
    778      * object type (comment, post, term, or user). Returning a non-null value
    779      * will effectively short-circuit the function.
     787     * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     788     * (post, comment, term, user, or any other type with an associated meta table).
     789     * Returning a non-null value will effectively short-circuit the function.
    780790     *
    781791     * @since 5.0.0
     
    891901     * Short-circuits deleting metadata of a specific type by meta ID.
    892902     *
    893      * The dynamic portion of the hook, `$meta_type`, refers to the meta
    894      * object type (comment, post, term, or user). Returning a non-null value
    895      * will effectively short-circuit the function.
     903     * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     904     * (post, comment, term, user, or any other type with an associated meta table).
     905     * Returning a non-null value will effectively short-circuit the function.
    896906     *
    897907     * @since 5.0.0
     
    9961006     * Short-circuits updating the metadata cache of a specific type.
    9971007     *
    998      * The dynamic portion of the hook, `$meta_type`, refers to the meta
    999      * object type (comment, post, term, or user). Returning a non-null value
    1000      * will effectively short-circuit the function.
     1008     * The dynamic portion of the hook, `$meta_type`, refers to the meta object type
     1009     * (post, comment, term, user, or any other type with an associated meta table).
     1010     * Returning a non-null value will effectively short-circuit the function.
    10011011     *
    10021012     * @since 5.0.0
     
    13651375
    13661376/**
     1377 * Filters into default_{$object_type}_metadata and adds in default value.
     1378 *
     1379 * @since 5.5.0
     1380 *
     1381 * @param mixed  $value     Current value passed to filter.
     1382 * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
     1383 *                          or any other object type with an associated meta table.
     1384 * @param string $meta_key  Metadata key.
     1385 * @param bool   $single    If true, return only the first value of the specified meta_key.
     1386 *                          This parameter has no effect if meta_key is not specified.
     1387 * @param int    $object_id ID of the object metadata is for.
     1388 * @return mixed Single metadata default, or array of defaults.
     1389 */
     1390function filter_default_metadata( $value, $meta_type, $meta_key, $single, $object_id ) {
     1391    global $wp_meta_keys;
     1392
     1393    if ( wp_installing() ) {
     1394        return $value;
     1395    }
     1396
     1397    if ( ! is_array( $wp_meta_keys ) || ! isset( $wp_meta_keys[ $meta_type ] ) ) {
     1398        return $value;
     1399    }
     1400
     1401    $defaults = array();
     1402    foreach ( $wp_meta_keys[ $meta_type ] as $sub_type => $meta_data ) {
     1403        foreach ( $meta_data as $_meta_key => $args ) {
     1404            if ( $_meta_key === $meta_key && array_key_exists( 'default', $args ) ) {
     1405                $defaults[ $sub_type ] = $args;
     1406            }
     1407        }
     1408    }
     1409
     1410    if ( ! $defaults ) {
     1411        return $value;
     1412    }
     1413
     1414    // If this meta type does not have sub types, then the default is keyed as an empty string.
     1415    if ( isset( $defaults[''] ) ) {
     1416        $metadata = $defaults[''];
     1417    } else {
     1418        $sub_type = get_object_subtype( $meta_type, $object_id );
     1419        if ( ! isset( $defaults[ $sub_type ] ) ) {
     1420            return $value;
     1421        }
     1422        $metadata = $defaults[ $sub_type ];
     1423    }
     1424
     1425    if ( $single ) {
     1426        $value = $metadata['default'];
     1427    } else {
     1428        $value = array( $metadata['default'] );
     1429    }
     1430
     1431    return $value;
     1432}
     1433
     1434/**
    13671435 * Checks if a meta key is registered.
    13681436 *
     
    15741642     * Filters the object subtype identifier for a non-standard object type.
    15751643     *
    1576      * The dynamic portion of the hook, `$object_type`, refers to the object
    1577      * type (post, comment, term, or user).
     1644     * The dynamic portion of the hook, `$object_type`, refers to the meta object type
     1645     * (post, comment, term, user, or any other type with an associated meta table).
    15781646     *
    15791647     * @since 4.9.8
     
    15841652    return apply_filters( "get_object_subtype_{$object_type}", $object_subtype, $object_id );
    15851653}
    1586 
    1587 /**
    1588  * Filter into default_{$object_type}_metadata and add in default value.
    1589  *
    1590  * @since 5.5.0
    1591  *
    1592  * @param mixed  $value     Current value passed to filter.
    1593  * @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
    1594 
    1595  * @param string $meta_key  Optional. Metadata key. If not specified, retrieve all metadata for
    1596  *                          the specified object.
    1597  * @param bool   $single    Optional, default is false.
    1598  *                          If true, return only the first value of the specified meta_key.
    1599  *                          This parameter has no effect if meta_key is not specified.
    1600  * @param int    $object_id ID of the object metadata is for
    1601  *
    1602  * @return mixed Single metadata default, or array of defaults
    1603  */
    1604 function filter_default_metadata( $value, $meta_type, $meta_key, $single, $object_id ) {
    1605     global $wp_meta_keys;
    1606 
    1607     if ( wp_installing() ) {
    1608         return $value;
    1609     }
    1610 
    1611     if ( ! is_array( $wp_meta_keys ) || ! isset( $wp_meta_keys[ $meta_type ] ) ) {
    1612         return $value;
    1613     }
    1614 
    1615     $defaults = array();
    1616     foreach ( $wp_meta_keys[ $meta_type ] as $sub_type => $meta_data ) {
    1617         foreach ( $meta_data as $_meta_key => $args ) {
    1618             if ( $_meta_key === $meta_key && array_key_exists( 'default', $args ) ) {
    1619                 $defaults[ $sub_type ] = $args;
    1620             }
    1621         }
    1622     }
    1623 
    1624     if ( ! $defaults ) {
    1625         return $value;
    1626     }
    1627 
    1628     // If this meta type does not have sub types, then the default is keyed as an empty string.
    1629     if ( isset( $defaults[''] ) ) {
    1630         $metadata = $defaults[''];
    1631     } else {
    1632         $sub_type = get_object_subtype( $meta_type, $object_id );
    1633         if ( ! isset( $defaults[ $sub_type ] ) ) {
    1634             return $value;
    1635         }
    1636         $metadata = $defaults[ $sub_type ];
    1637     }
    1638 
    1639     if ( $single ) {
    1640         $value = $metadata['default'];
    1641     } else {
    1642         $value = array( $metadata['default'] );
    1643     }
    1644 
    1645     return $value;
    1646 }
  • trunk/src/wp-includes/rest-api/fields/class-wp-rest-meta-fields.php

    r48402 r48411  
    8080            $name       = $args['name'];
    8181            $all_values = get_metadata( $this->get_meta_type(), $object_id, $meta_key, false );
     82
    8283            if ( $args['single'] ) {
    8384                if ( empty( $all_values ) ) {
  • trunk/tests/phpunit/tests/meta/registerMeta.php

    r48402 r48411  
    667667            ),
    668668
    669             // types
     669            // Types.
    670670            'single object key with single ask'           => array(
    671671                array(
Note: See TracChangeset for help on using the changeset viewer.