Changeset 48402 for trunk/src/wp-includes/meta.php

Timestamp:

07/07/2020 08:45:55 PM (5 years ago)

Author:

TimothyBlynJacobs

Message:

REST API, Meta: Introduce support for default metadata values.

The register_meta() API now officially supports specifying a default metadata value. When get_metadata() is called for a meta key that does not yet exist for the object, this default value will be returned instead of an empty string.

A new function is introduced get_metadata_raw to retrieve the raw metadata value from the database, without applying the registered default.

Props spacedmonkey, flixos90, rmccue, kadamwhite, mnelson4, johnbillion, chrisvanpatten, TimothyBlynJacobs.
Fixes #43941.

File:

• trunk/src/wp-includes/meta.php (modified) (9 diffs)

trunk/src/wp-includes/meta.php

@@ -211 +211 @@
     // Compare existing value to new value if no prev value given and the key exists only once.
     if ( empty( $prev_value ) ) {
-        $old_value = get_metadata( $meta_type, $object_id, $meta_key );
-        if ( count( $old_value ) == 1 ) {
+        $old_value = get_metadata_raw( $meta_type, $object_id, $meta_key );
+        if ( is_countable( $old_value ) && count( $old_value ) === 1 ) {
             if ( $old_value[0] === $meta_value ) {
                 return false;
@@ -486 +486 @@
  * If there's a problem with the parameters passed to the function, boolean `false` is returned.
  *
- * @since 2.9.0
+ * @since 5.5.0
  *
  * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
@@ -497 +497 @@
  * @return mixed The metadata value or array of values. See description above for further details.
  */
-function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) {
+function get_metadata_raw( $meta_type, $object_id, $meta_key = '', $single = false ) {
     if ( ! $meta_type || ! is_numeric( $object_id ) ) {
         return false;
@@ -554 +554 @@
     }
 
+    return null;
+}
+
+/**
+ * Retrieves raw metadata for the specified object.
+ *
+ * @since 2.9.0
+ * @uses get_metadata_raw()
+ *
+ * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
+ *                          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  Optional. Metadata key. If not specified, retrieve all metadata for
+ *                          the specified object. Default empty.
+ * @param bool   $single    Optional. If true, return only the first value of the specified meta_key.
+ *                          This parameter has no effect if meta_key is not specified. Default false.
+ * @return mixed Single metadata value, or array of values
+ */
+function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) {
+    $value = get_metadata_raw( $meta_type, $object_id, $meta_key, $single );
+    if ( ! is_null( $value ) ) {
+        return $value;
+    }
+
+    return get_metadata_default( $meta_type, $meta_key, $single, $object_id );
+}
+
+/**
+ * Retrieve metadata data default for the specified object.
+ *
+ * @since 5.5.0
+ *
+ * @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
+ * @param string $meta_key  Optional. Metadata key. If not specified, retrieve all metadata for
+ *                          the specified object.
+ * @param bool   $single    Optional, default is false.
+ *                          If true, return only the first value of the specified meta_key.
+ *                          This parameter has no effect if meta_key is not specified.
+ * @param int    $object_id Optional, default is 0.
+ *                          ID of the object metadata is for
+ * @return mixed Single metadata value, or array of values
+ */
+function get_metadata_default( $meta_type, $meta_key, $single = false, $object_id = 0 ) {
     if ( $single ) {
-        return '';
+        $value = '';
     } else {
-        return array();
-    }
+        $value = array();
+    }
+
+    /**
+     * Filter the default value a specified object.
+     *
+     * @since 5.5.0
+     *
+     * @param array|string      $value     The value should return - a single metadata value,
+     *                                     or an array of values.
+     * @param string            $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
+     * @param string            $meta_key  Meta key.
+     * @param bool              $single    Whether to return only the first value of the specified $meta_key.
+     * @param int               $object_id Object ID.
+     */
+    $value = apply_filters( "default_{$meta_type}_metadata", $value, $meta_type, $meta_key, $single, $object_id );
+
+    if ( ! $single && ! wp_is_numeric_array( $value ) ) {
+        $value = array( $value );
+    }
+
+    return $value;
 }
 
@@ -1164 +1227 @@
  *     @type string     $description       A description of the data attached to this meta key.
  *     @type bool       $single            Whether the meta key has one value per object, or an array of values per object.
+ *     @type mixed      $default           The default value returned from {@see get_metadata()} if no value has been set yet.
+ *                                         When using a non-single meta key, the default value is for the first entry. In other
+ *                                         words, when calling {@see get_metadata()} with `$single` set to `false`, the default
+ *                                         value given here will be wrapped in an array.
  *     @type string     $sanitize_callback A function or method to call when sanitizing `$meta_key` data.
  *     @type string     $auth_callback     Optional. A function or method to call when performing edit_post_meta,
@@ -1189 +1256 @@
         'type'              => 'string',
         'description'       => '',
+        'default'           => '',
         'single'            => false,
         'sanitize_callback' => null,
@@ -1226 +1294 @@
      */
     $args = apply_filters( 'register_meta_args', $args, $defaults, $object_type, $meta_key );
+    unset( $defaults['default'] );
     $args = wp_parse_args( $args, $defaults );
 
@@ -1262 +1331 @@
         } else {
             add_filter( "auth_{$object_type}_meta_{$meta_key}", $args['auth_callback'], 10, 6 );
+        }
+    }
+
+    if ( array_key_exists( 'default', $args ) ) {
+        $schema = $args;
+        if ( is_array( $args['show_in_rest'] ) && isset( $args['show_in_rest']['schema'] ) ) {
+            $schema = array_merge( $schema, $args['show_in_rest']['schema'] );
+        }
+
+        $check = rest_validate_value_from_schema( $args['default'], $schema );
+        if ( is_wp_error( $check ) ) {
+            _doing_it_wrong( __FUNCTION__, __( 'When registering a default meta value the data must match the type provided.' ), '5.5.0' );
+
+            return false;
+        }
+
+        if ( ! has_filter( "default_{$object_type}_metadata", 'filter_default_metadata' ) ) {
+            add_filter( "default_{$object_type}_metadata", 'filter_default_metadata', 10, 5 );
         }
     }
@@ -1497 +1584 @@
     return apply_filters( "get_object_subtype_{$object_type}", $object_subtype, $object_id );
 }
+
+/**
+ * Filter into default_{$object_type}_metadata and add in default value.
+ *
+ * @since 5.5.0
+ *
+ * @param mixed  $value     Current value passed to filter.
+ * @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
+
+ * @param string $meta_key  Optional. Metadata key. If not specified, retrieve all metadata for
+ *                          the specified object.
+ * @param bool   $single    Optional, default is false.
+ *                          If true, return only the first value of the specified meta_key.
+ *                          This parameter has no effect if meta_key is not specified.
+ * @param int    $object_id ID of the object metadata is for
+ *
+ * @return mixed Single metadata default, or array of defaults
+ */
+function filter_default_metadata( $value, $meta_type, $meta_key, $single, $object_id ) {
+    global $wp_meta_keys;
+
+    if ( wp_installing() ) {
+        return $value;
+    }
+
+    if ( ! is_array( $wp_meta_keys ) || ! isset( $wp_meta_keys[ $meta_type ] ) ) {
+        return $value;
+    }
+
+    $defaults = array();
+    foreach ( $wp_meta_keys[ $meta_type ] as $sub_type => $meta_data ) {
+        foreach ( $meta_data as $_meta_key => $args ) {
+            if ( $_meta_key === $meta_key && array_key_exists( 'default', $args ) ) {
+                $defaults[ $sub_type ] = $args;
+            }
+        }
+    }
+
+    if ( ! $defaults ) {
+        return $value;
+    }
+
+    // If this meta type does not have sub types, then the default is keyed as an empty string.
+    if ( isset( $defaults[''] ) ) {
+        $metadata = $defaults[''];
+    } else {
+        $sub_type = get_object_subtype( $meta_type, $object_id );
+        if ( ! isset( $defaults[ $sub_type ] ) ) {
+            return $value;
+        }
+        $metadata = $defaults[ $sub_type ];
+    }
+
+    if ( $single ) {
+        $value = $metadata['default'];
+    } else {
+        $value = array( $metadata['default'] );
+    }
+
+    return $value;
+}