123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625 |
- <?php
- /**
- * REST API: WP_REST_Meta_Fields class
- *
- * @package WordPress
- * @subpackage REST_API
- * @since 4.7.0
- */
- /**
- * Core class to manage meta values for an object via the REST API.
- *
- * @since 4.7.0
- */
- #[AllowDynamicProperties]
- abstract class WP_REST_Meta_Fields {
- /**
- * Retrieves the object meta type.
- *
- * @since 4.7.0
- *
- * @return string One of 'post', 'comment', 'term', 'user', or anything
- * else supported by `_get_meta_table()`.
- */
- abstract protected function get_meta_type();
- /**
- * Retrieves the object meta subtype.
- *
- * @since 4.9.8
- *
- * @return string Subtype for the meta type, or empty string if no specific subtype.
- */
- protected function get_meta_subtype() {
- return '';
- }
- /**
- * Retrieves the object type for register_rest_field().
- *
- * @since 4.7.0
- *
- * @return string The REST field type, such as post type name, taxonomy name, 'comment', or `user`.
- */
- abstract protected function get_rest_field_type();
- /**
- * Registers the meta field.
- *
- * @since 4.7.0
- * @deprecated 5.6.0
- *
- * @see register_rest_field()
- */
- public function register_field() {
- _deprecated_function( __METHOD__, '5.6.0' );
- register_rest_field(
- $this->get_rest_field_type(),
- 'meta',
- array(
- 'get_callback' => array( $this, 'get_value' ),
- 'update_callback' => array( $this, 'update_value' ),
- 'schema' => $this->get_field_schema(),
- )
- );
- }
- /**
- * Retrieves the meta field value.
- *
- * @since 4.7.0
- *
- * @param int $object_id Object ID to fetch meta for.
- * @param WP_REST_Request $request Full details about the request.
- * @return array Array containing the meta values keyed by name.
- */
- public function get_value( $object_id, $request ) {
- $fields = $this->get_registered_fields();
- $response = array();
- foreach ( $fields as $meta_key => $args ) {
- $name = $args['name'];
- $all_values = get_metadata( $this->get_meta_type(), $object_id, $meta_key, false );
- if ( $args['single'] ) {
- if ( empty( $all_values ) ) {
- $value = $args['schema']['default'];
- } else {
- $value = $all_values[0];
- }
- $value = $this->prepare_value_for_response( $value, $request, $args );
- } else {
- $value = array();
- if ( is_array( $all_values ) ) {
- foreach ( $all_values as $row ) {
- $value[] = $this->prepare_value_for_response( $row, $request, $args );
- }
- }
- }
- $response[ $name ] = $value;
- }
- return $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
- * type before passing back to JSON.
- *
- * @since 4.7.0
- *
- * @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.
- */
- protected function prepare_value_for_response( $value, $request, $args ) {
- if ( ! empty( $args['prepare_callback'] ) ) {
- $value = call_user_func( $args['prepare_callback'], $value, $request, $args );
- }
- return $value;
- }
- /**
- * Updates meta values.
- *
- * @since 4.7.0
- *
- * @param array $meta Array of meta parsed from the request.
- * @param int $object_id Object ID to fetch meta for.
- * @return null|WP_Error Null on success, WP_Error object on failure.
- */
- public function update_value( $meta, $object_id ) {
- $fields = $this->get_registered_fields();
- foreach ( $fields as $meta_key => $args ) {
- $name = $args['name'];
- if ( ! array_key_exists( $name, $meta ) ) {
- continue;
- }
- $value = $meta[ $name ];
- /*
- * A null value means reset the field, which is essentially deleting it
- * from the database and then relying on the default value.
- *
- * Non-single meta can also be removed by passing an empty array.
- */
- if ( is_null( $value ) || ( array() === $value && ! $args['single'] ) ) {
- $args = $this->get_registered_fields()[ $meta_key ];
- if ( $args['single'] ) {
- $current = get_metadata( $this->get_meta_type(), $object_id, $meta_key, true );
- if ( is_wp_error( rest_validate_value_from_schema( $current, $args['schema'] ) ) ) {
- return new WP_Error(
- 'rest_invalid_stored_value',
- /* translators: %s: Custom field key. */
- sprintf( __( 'The %s property has an invalid stored value, and cannot be updated to null.' ), $name ),
- array( 'status' => 500 )
- );
- }
- }
- $result = $this->delete_meta_value( $object_id, $meta_key, $name );
- if ( is_wp_error( $result ) ) {
- return $result;
- }
- continue;
- }
- if ( ! $args['single'] && is_array( $value ) && count( array_filter( $value, 'is_null' ) ) ) {
- return new WP_Error(
- 'rest_invalid_stored_value',
- /* translators: %s: Custom field key. */
- sprintf( __( 'The %s property has an invalid stored value, and cannot be updated to null.' ), $name ),
- array( 'status' => 500 )
- );
- }
- $is_valid = rest_validate_value_from_schema( $value, $args['schema'], 'meta.' . $name );
- if ( is_wp_error( $is_valid ) ) {
- $is_valid->add_data( array( 'status' => 400 ) );
- return $is_valid;
- }
- $value = rest_sanitize_value_from_schema( $value, $args['schema'] );
- if ( $args['single'] ) {
- $result = $this->update_meta_value( $object_id, $meta_key, $name, $value );
- } else {
- $result = $this->update_multi_meta_value( $object_id, $meta_key, $name, $value );
- }
- if ( is_wp_error( $result ) ) {
- return $result;
- }
- }
- return null;
- }
- /**
- * Deletes a meta value for an object.
- *
- * @since 4.7.0
- *
- * @param int $object_id Object ID the field belongs to.
- * @param string $meta_key Key for the field.
- * @param string $name Name for the field that is exposed in the REST API.
- * @return true|WP_Error True if meta field is deleted, WP_Error otherwise.
- */
- protected function delete_meta_value( $object_id, $meta_key, $name ) {
- $meta_type = $this->get_meta_type();
- if ( ! current_user_can( "delete_{$meta_type}_meta", $object_id, $meta_key ) ) {
- return new WP_Error(
- 'rest_cannot_delete',
- /* translators: %s: Custom field key. */
- sprintf( __( 'Sorry, you are not allowed to edit the %s custom field.' ), $name ),
- array(
- 'key' => $name,
- 'status' => rest_authorization_required_code(),
- )
- );
- }
- if ( null === get_metadata_raw( $meta_type, $object_id, wp_slash( $meta_key ) ) ) {
- return true;
- }
- if ( ! delete_metadata( $meta_type, $object_id, wp_slash( $meta_key ) ) ) {
- return new WP_Error(
- 'rest_meta_database_error',
- __( 'Could not delete meta value from database.' ),
- array(
- 'key' => $name,
- 'status' => WP_Http::INTERNAL_SERVER_ERROR,
- )
- );
- }
- return true;
- }
- /**
- * 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
- *
- * @param int $object_id Object ID to update.
- * @param string $meta_key Key for the custom field.
- * @param string $name Name for the field that is exposed in the REST API.
- * @param array $values List of values to update to.
- * @return true|WP_Error True if meta fields are updated, WP_Error otherwise.
- */
- protected function update_multi_meta_value( $object_id, $meta_key, $name, $values ) {
- $meta_type = $this->get_meta_type();
- if ( ! current_user_can( "edit_{$meta_type}_meta", $object_id, $meta_key ) ) {
- return new WP_Error(
- 'rest_cannot_update',
- /* translators: %s: Custom field key. */
- sprintf( __( 'Sorry, you are not allowed to edit the %s custom field.' ), $name ),
- array(
- 'key' => $name,
- 'status' => rest_authorization_required_code(),
- )
- );
- }
- $current_values = get_metadata( $meta_type, $object_id, $meta_key, false );
- $subtype = get_object_subtype( $meta_type, $object_id );
- if ( ! is_array( $current_values ) ) {
- $current_values = array();
- }
- $to_remove = $current_values;
- $to_add = $values;
- foreach ( $to_add as $add_key => $value ) {
- $remove_keys = array_keys(
- array_filter(
- $current_values,
- function ( $stored_value ) use ( $meta_key, $subtype, $value ) {
- return $this->is_meta_value_same_as_stored_value( $meta_key, $subtype, $stored_value, $value );
- }
- )
- );
- if ( empty( $remove_keys ) ) {
- continue;
- }
- if ( count( $remove_keys ) > 1 ) {
- // To remove, we need to remove first, then add, so don't touch.
- continue;
- }
- $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. Otherwise,
- * `delete_metadata` will return false for subsequent calls of the same value.
- * Use serialization to produce a predictable string that can be used by array_unique.
- */
- $to_remove = array_map( 'maybe_unserialize', array_unique( array_map( 'maybe_serialize', $to_remove ) ) );
- foreach ( $to_remove as $value ) {
- if ( ! delete_metadata( $meta_type, $object_id, wp_slash( $meta_key ), wp_slash( $value ) ) ) {
- return new WP_Error(
- 'rest_meta_database_error',
- /* translators: %s: Custom field key. */
- sprintf( __( 'Could not update the meta value of %s in database.' ), $meta_key ),
- array(
- 'key' => $name,
- 'status' => WP_Http::INTERNAL_SERVER_ERROR,
- )
- );
- }
- }
- foreach ( $to_add as $value ) {
- if ( ! add_metadata( $meta_type, $object_id, wp_slash( $meta_key ), wp_slash( $value ) ) ) {
- return new WP_Error(
- 'rest_meta_database_error',
- /* translators: %s: Custom field key. */
- sprintf( __( 'Could not update the meta value of %s in database.' ), $meta_key ),
- array(
- 'key' => $name,
- 'status' => WP_Http::INTERNAL_SERVER_ERROR,
- )
- );
- }
- }
- return true;
- }
- /**
- * Updates a meta value for an object.
- *
- * @since 4.7.0
- *
- * @param int $object_id Object ID to update.
- * @param string $meta_key Key for the custom field.
- * @param string $name Name for the field that is exposed in the REST API.
- * @param mixed $value Updated value.
- * @return true|WP_Error True if the meta field was updated, WP_Error otherwise.
- */
- protected function update_meta_value( $object_id, $meta_key, $name, $value ) {
- $meta_type = $this->get_meta_type();
- if ( ! current_user_can( "edit_{$meta_type}_meta", $object_id, $meta_key ) ) {
- return new WP_Error(
- 'rest_cannot_update',
- /* translators: %s: Custom field key. */
- sprintf( __( 'Sorry, you are not allowed to edit the %s custom field.' ), $name ),
- array(
- 'key' => $name,
- 'status' => rest_authorization_required_code(),
- )
- );
- }
- // 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 );
- $subtype = get_object_subtype( $meta_type, $object_id );
- if ( is_array( $old_value ) && 1 === count( $old_value )
- && $this->is_meta_value_same_as_stored_value( $meta_key, $subtype, $old_value[0], $value )
- ) {
- return true;
- }
- if ( ! update_metadata( $meta_type, $object_id, wp_slash( $meta_key ), wp_slash( $value ) ) ) {
- return new WP_Error(
- 'rest_meta_database_error',
- /* translators: %s: Custom field key. */
- sprintf( __( 'Could not update the meta value of %s in database.' ), $meta_key ),
- array(
- 'key' => $name,
- 'status' => WP_Http::INTERNAL_SERVER_ERROR,
- )
- );
- }
- return true;
- }
- /**
- * Checks if the user provided value is equivalent to a stored value for the given meta key.
- *
- * @since 5.5.0
- *
- * @param string $meta_key The meta key being checked.
- * @param string $subtype The object subtype.
- * @param mixed $stored_value The currently stored value retrieved from get_metadata().
- * @param mixed $user_value The value provided by the user.
- * @return bool
- */
- protected function is_meta_value_same_as_stored_value( $meta_key, $subtype, $stored_value, $user_value ) {
- $args = $this->get_registered_fields()[ $meta_key ];
- $sanitized = sanitize_meta( $meta_key, $user_value, $this->get_meta_type(), $subtype );
- if ( in_array( $args['type'], array( 'string', 'number', 'integer', 'boolean' ), true ) ) {
- // The return value of get_metadata will always be a string for scalar types.
- $sanitized = (string) $sanitized;
- }
- return $sanitized === $stored_value;
- }
- /**
- * Retrieves all the registered meta fields.
- *
- * @since 4.7.0
- *
- * @return array Registered fields.
- */
- protected function get_registered_fields() {
- $registered = array();
- $meta_type = $this->get_meta_type();
- $meta_subtype = $this->get_meta_subtype();
- $meta_keys = get_registered_meta_keys( $meta_type );
- if ( ! empty( $meta_subtype ) ) {
- $meta_keys = array_merge( $meta_keys, get_registered_meta_keys( $meta_type, $meta_subtype ) );
- }
- foreach ( $meta_keys as $name => $args ) {
- if ( empty( $args['show_in_rest'] ) ) {
- continue;
- }
- $rest_args = array();
- if ( is_array( $args['show_in_rest'] ) ) {
- $rest_args = $args['show_in_rest'];
- }
- $default_args = array(
- 'name' => $name,
- 'single' => $args['single'],
- 'type' => ! empty( $args['type'] ) ? $args['type'] : null,
- 'schema' => array(),
- 'prepare_callback' => array( $this, 'prepare_value' ),
- );
- $default_schema = array(
- 'type' => $default_args['type'],
- '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'] );
- $type = ! empty( $rest_args['type'] ) ? $rest_args['type'] : null;
- $type = ! empty( $rest_args['schema']['type'] ) ? $rest_args['schema']['type'] : $type;
- if ( null === $rest_args['schema']['default'] ) {
- $rest_args['schema']['default'] = static::get_empty_value_for_type( $type );
- }
- $rest_args['schema'] = rest_default_additional_properties_to_false( $rest_args['schema'] );
- if ( ! in_array( $type, array( 'string', 'boolean', 'integer', 'number', 'array', 'object' ), true ) ) {
- continue;
- }
- if ( empty( $rest_args['single'] ) ) {
- $rest_args['schema'] = array(
- 'type' => 'array',
- 'items' => $rest_args['schema'],
- );
- }
- $registered[ $name ] = $rest_args;
- }
- return $registered;
- }
- /**
- * Retrieves the object's meta schema, conforming to JSON Schema.
- *
- * @since 4.7.0
- *
- * @return array Field schema data.
- */
- public function get_field_schema() {
- $fields = $this->get_registered_fields();
- $schema = array(
- 'description' => __( 'Meta fields.' ),
- 'type' => 'object',
- 'context' => array( 'view', 'edit' ),
- 'properties' => array(),
- 'arg_options' => array(
- 'sanitize_callback' => null,
- 'validate_callback' => array( $this, 'check_meta_is_array' ),
- ),
- );
- foreach ( $fields as $args ) {
- $schema['properties'][ $args['name'] ] = $args['schema'];
- }
- return $schema;
- }
- /**
- * 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
- *
- * @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. If a non-JsonSerializable object, null.
- */
- public static function prepare_value( $value, $request, $args ) {
- if ( $args['single'] ) {
- $schema = $args['schema'];
- } else {
- $schema = $args['schema']['items'];
- }
- if ( '' === $value && in_array( $schema['type'], array( 'boolean', 'integer', 'number' ), true ) ) {
- $value = static::get_empty_value_for_type( $schema['type'] );
- }
- if ( is_wp_error( rest_validate_value_from_schema( $value, $schema ) ) ) {
- return null;
- }
- return rest_sanitize_value_from_schema( $value, $schema );
- }
- /**
- * Check the 'meta' value of a request is an associative array.
- *
- * @since 4.7.0
- *
- * @param mixed $value The meta value submitted in the request.
- * @param WP_REST_Request $request Full details about the request.
- * @param string $param The parameter name.
- * @return array|false The meta array, if valid, false otherwise.
- */
- public function check_meta_is_array( $value, $request, $param ) {
- if ( ! is_array( $value ) ) {
- return false;
- }
- return $value;
- }
- /**
- * Recursively add additionalProperties = false to all objects in a schema if no additionalProperties setting
- * is specified.
- *
- * This is needed to restrict properties of objects in meta values to only
- * registered items, as the REST API will allow additional properties by
- * default.
- *
- * @since 5.3.0
- * @deprecated 5.6.0 Use rest_default_additional_properties_to_false() instead.
- *
- * @param array $schema The schema array.
- * @return array
- */
- protected function default_additional_properties_to_false( $schema ) {
- _deprecated_function( __METHOD__, '5.6.0', 'rest_default_additional_properties_to_false()' );
- return rest_default_additional_properties_to_false( $schema );
- }
- /**
- * Gets the empty value for a schema type.
- *
- * @since 5.3.0
- *
- * @param string $type The schema type.
- * @return mixed
- */
- protected static function get_empty_value_for_type( $type ) {
- switch ( $type ) {
- case 'string':
- return '';
- case 'boolean':
- return false;
- case 'integer':
- return 0;
- case 'number':
- return 0.0;
- case 'array':
- case 'object':
- return array();
- default:
- return null;
- }
- }
- }
|