From 79ed959c30a96a5e4e9af7262319b673d770ef03 Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Sun, 30 Oct 2016 16:32:05 +0000 Subject: [PATCH] Docs: Add much more complete and syntactically correct documentation throughout the `WP_REST_Meta_Fields` class. Props Soean, mrahmadawais, flixos90. See #38398. git-svn-id: https://develop.svn.wordpress.org/trunk@39022 602fd350-edb4-49c9-b593-d223f7449a82 --- .../fields/class-wp-rest-meta-fields.php | 127 +++++++++++++----- 1 file changed, 92 insertions(+), 35 deletions(-) diff --git a/src/wp-includes/rest-api/fields/class-wp-rest-meta-fields.php b/src/wp-includes/rest-api/fields/class-wp-rest-meta-fields.php index 505a3e3da9..a85424e467 100644 --- a/src/wp-includes/rest-api/fields/class-wp-rest-meta-fields.php +++ b/src/wp-includes/rest-api/fields/class-wp-rest-meta-fields.php @@ -1,12 +1,24 @@ get_rest_field_type(), 'meta', array( - 'get_callback' => array( $this, 'get_value' ), + 'get_callback' => array( $this, 'get_value' ), 'update_callback' => array( $this, 'update_value' ), - 'schema' => $this->get_field_schema(), + 'schema' => $this->get_field_schema(), )); } /** - * Get the `meta` field value. + * Retrieves the meta field value. + * + * @since 4.7.0 + * @access public * * @param int $object_id Object ID to fetch meta for. * @param WP_REST_Request $request Full details about the request. - * @return WP_Error|object + * @return WP_Error|object Object containing the meta values by name, otherwise WP_Error object. */ public function get_value( $object_id, $request ) { $fields = $this->get_registered_fields(); @@ -65,13 +88,16 @@ abstract class WP_REST_Meta_Fields { } /** - * Prepare value for response. + * Prepares a meta value for a response. * - * This is required because some native types cannot be stored correctly in - * the database, such as booleans. We need to cast back to the relevant + * This is required because some native types cannot be stored correctly + * in the database, such as booleans. We need to cast back to the relevant * type before passing back to JSON. * - * @param mixed $value Value to prepare. + * @since 4.7.0 + * @access protected + * + * @param mixed $value Meta value to prepare. * @param WP_REST_Request $request Current request object. * @param array $args Options for the field. * @return mixed Prepared value. @@ -85,11 +111,14 @@ abstract class WP_REST_Meta_Fields { } /** - * Update meta values. + * Updates meta values. * - * @param WP_REST_Request $request Full details about the request. - * @param int $object_id Object ID to fetch meta for. - * @return WP_Error|null Error if one occurs, null on success. + * @since 4.7.0 + * @access public + * + * @param WP_REST_Request $request Full details about the request. + * @param int $object_id Object ID to fetch meta for. + * @return WP_Error|null WP_Error if one occurs, null on success. */ public function update_value( $request, $object_id ) { $fields = $this->get_registered_fields(); @@ -99,8 +128,10 @@ abstract class WP_REST_Meta_Fields { continue; } - // A null value means reset the field, which is essentially deleting it - // from the database and then relying on the default value. + /* + * A null value means reset the field, which is essentially deleting it + * from the database and then relying on the default value. + */ if ( is_null( $request[ $name ] ) ) { $result = $this->delete_meta_value( $object_id, $name ); } elseif ( $args['single'] ) { @@ -118,11 +149,14 @@ abstract class WP_REST_Meta_Fields { } /** - * Delete meta value for an object. + * Deletes a meta value for an object. + * + * @since 4.7.0 + * @access protected * * @param int $object_id Object ID the field belongs to. * @param string $name Key for the field. - * @return bool|WP_Error True if meta field is deleted, error otherwise. + * @return bool|WP_Error True if meta field is deleted, WP_Error otherwise. */ protected function delete_meta_value( $object_id, $name ) { if ( ! current_user_can( 'delete_post_meta', $object_id, $name ) ) { @@ -145,14 +179,17 @@ abstract class WP_REST_Meta_Fields { } /** - * Update multiple meta values for an object. + * Updates multiple meta values for an object. * * Alters the list of values in the database to match the list of provided values. * + * @since 4.7.0 + * @access protected + * * @param int $object_id Object ID to update. * @param string $name Key for the custom field. * @param array $values List of values to update to. - * @return bool|WP_Error True if meta fields are updated, error otherwise. + * @return bool|WP_Error True if meta fields are updated, WP_Error otherwise. */ protected function update_multi_meta_value( $object_id, $name, $values ) { if ( ! current_user_can( 'edit_post_meta', $object_id, $name ) ) { @@ -166,9 +203,11 @@ abstract class WP_REST_Meta_Fields { $current = get_metadata( $this->get_meta_type(), $object_id, $name, false ); $to_remove = $current; - $to_add = $values; + $to_add = $values; + foreach ( $to_add as $add_key => $value ) { $remove_keys = array_keys( $to_remove, $value, true ); + if ( empty( $remove_keys ) ) { continue; } @@ -179,13 +218,14 @@ abstract class WP_REST_Meta_Fields { } $remove_key = $remove_keys[0]; + unset( $to_remove[ $remove_key ] ); unset( $to_add[ $add_key ] ); } - // `delete_metadata` removes _all_ instances of the value, so only call - // once. + // `delete_metadata` removes _all_ instances of the value, so only call once. $to_remove = array_unique( $to_remove ); + foreach ( $to_remove as $value ) { if ( ! delete_metadata( $this->get_meta_type(), $object_id, wp_slash( $name ), wp_slash( $value ) ) ) { return new WP_Error( @@ -195,6 +235,7 @@ abstract class WP_REST_Meta_Fields { ); } } + foreach ( $to_add as $value ) { if ( ! add_metadata( $this->get_meta_type(), $object_id, wp_slash( $name ), wp_slash( $value ) ) ) { return new WP_Error( @@ -209,12 +250,15 @@ abstract class WP_REST_Meta_Fields { } /** - * Update meta value for an object. + * Updates a meta value for an object. + * + * @since 4.7.0 + * @access protected * * @param int $object_id Object ID to update. * @param string $name Key for the custom field. * @param mixed $value Updated value. - * @return bool|WP_Error True if meta field is updated, error otherwise. + * @return bool|WP_Error True if the meta field was updated, WP_Error otherwise. */ protected function update_meta_value( $object_id, $name, $value ) { if ( ! current_user_can( 'edit_post_meta', $object_id, $name ) ) { @@ -231,6 +275,7 @@ abstract class WP_REST_Meta_Fields { // Do the exact same check for a duplicate value as in update_metadata() to avoid update_metadata() returning false. $old_value = get_metadata( $meta_type, $object_id, $meta_key ); + if ( 1 === count( $old_value ) ) { if ( $old_value[0] === $meta_value ) { return true; @@ -249,9 +294,12 @@ abstract class WP_REST_Meta_Fields { } /** - * Get all the registered meta fields. + * Retrieves all the registered meta fields. * - * @return array + * @since 4.7.0 + * @access protected + * + * @return array Registered fields. */ protected function get_registered_fields() { $registered = array(); @@ -262,6 +310,7 @@ abstract class WP_REST_Meta_Fields { } $rest_args = array(); + if ( is_array( $args['show_in_rest'] ) ) { $rest_args = $args['show_in_rest']; } @@ -272,11 +321,13 @@ abstract class WP_REST_Meta_Fields { 'schema' => array(), 'prepare_callback' => array( $this, 'prepare_value' ), ); + $default_schema = array( 'type' => null, 'description' => empty( $args['description'] ) ? '' : $args['description'], 'default' => isset( $args['default'] ) ? $args['default'] : null, ); + $rest_args = array_merge( $default_args, $rest_args ); $rest_args['schema'] = array_merge( $default_schema, $rest_args['schema'] ); @@ -297,15 +348,18 @@ abstract class WP_REST_Meta_Fields { } $registered[ $rest_args['name'] ] = $rest_args; - } // End foreach(). + } return $registered; } /** - * Get the object's `meta` schema, conforming to JSON Schema. + * Retrieves the object's meta schema, conforming to JSON Schema. * - * @return array + * @since 4.7.0 + * @access protected + * + * @return array Field schema data. */ public function get_field_schema() { $fields = $this->get_registered_fields(); @@ -325,15 +379,18 @@ abstract class WP_REST_Meta_Fields { } /** - * Prepare a meta value for output. + * Prepares a meta value for output. * * Default preparation for meta fields. Override by passing the * `prepare_callback` in your `show_in_rest` options. * + * @since 4.7.0 + * @access public + * * @param mixed $value Meta value from the database. * @param WP_REST_Request $request Request object. * @param array $args REST-specific options for the meta key. - * @return mixed Value prepared for output. + * @return mixed Value prepared for output. If a non-JsonSerializable object, null. */ public static function prepare_value( $value, $request, $args ) { $type = $args['schema']['type'];