| [ Index ] |
PHP Cross Reference of WordPress |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * REST API: WP_REST_Meta_Fields class 4 * 5 * @package WordPress 6 * @subpackage REST_API 7 * @since 4.7.0 8 */ 9 10 /** 11 * Core class to manage meta values for an object via the REST API. 12 * 13 * @since 4.7.0 14 */ 15 abstract class WP_REST_Meta_Fields { 16 17 /** 18 * Retrieves the object meta type. 19 * 20 * @since 4.7.0 21 * 22 * @return string One of 'post', 'comment', 'term', 'user', or anything 23 * else supported by `_get_meta_table()`. 24 */ 25 abstract protected function get_meta_type(); 26 27 /** 28 * Retrieves the object meta subtype. 29 * 30 * @since 4.9.8 31 * 32 * @return string Subtype for the meta type, or empty string if no specific subtype. 33 */ 34 protected function get_meta_subtype() { 35 return ''; 36 } 37 38 /** 39 * Retrieves the object type for register_rest_field(). 40 * 41 * @since 4.7.0 42 * 43 * @return string The REST field type, such as post type name, taxonomy name, 'comment', or `user`. 44 */ 45 abstract protected function get_rest_field_type(); 46 47 /** 48 * Registers the meta field. 49 * 50 * @since 4.7.0 51 * 52 * @see register_rest_field() 53 */ 54 public function register_field() { 55 register_rest_field( 56 $this->get_rest_field_type(), 57 'meta', 58 array( 59 'get_callback' => array( $this, 'get_value' ), 60 'update_callback' => array( $this, 'update_value' ), 61 'schema' => $this->get_field_schema(), 62 ) 63 ); 64 } 65 66 /** 67 * Retrieves the meta field value. 68 * 69 * @since 4.7.0 70 * 71 * @param int $object_id Object ID to fetch meta for. 72 * @param WP_REST_Request $request Full details about the request. 73 * @return object|WP_Error Object containing the meta values by name, otherwise WP_Error object. 74 */ 75 public function get_value( $object_id, $request ) { 76 $fields = $this->get_registered_fields(); 77 $response = array(); 78 79 foreach ( $fields as $meta_key => $args ) { 80 $name = $args['name']; 81 $all_values = get_metadata( $this->get_meta_type(), $object_id, $meta_key, false ); 82 if ( $args['single'] ) { 83 if ( empty( $all_values ) ) { 84 $value = $args['schema']['default']; 85 } else { 86 $value = $all_values[0]; 87 } 88 $value = $this->prepare_value_for_response( $value, $request, $args ); 89 } else { 90 $value = array(); 91 foreach ( $all_values as $row ) { 92 $value[] = $this->prepare_value_for_response( $row, $request, $args ); 93 } 94 } 95 96 $response[ $name ] = $value; 97 } 98 99 return $response; 100 } 101 102 /** 103 * Prepares a meta value for a response. 104 * 105 * This is required because some native types cannot be stored correctly 106 * in the database, such as booleans. We need to cast back to the relevant 107 * type before passing back to JSON. 108 * 109 * @since 4.7.0 110 * 111 * @param mixed $value Meta value to prepare. 112 * @param WP_REST_Request $request Current request object. 113 * @param array $args Options for the field. 114 * @return mixed Prepared value. 115 */ 116 protected function prepare_value_for_response( $value, $request, $args ) { 117 if ( ! empty( $args['prepare_callback'] ) ) { 118 $value = call_user_func( $args['prepare_callback'], $value, $request, $args ); 119 } 120 121 return $value; 122 } 123 124 /** 125 * Updates meta values. 126 * 127 * @since 4.7.0 128 * 129 * @param array $meta Array of meta parsed from the request. 130 * @param int $object_id Object ID to fetch meta for. 131 * @return null|WP_Error Null on success, WP_Error object on failure. 132 */ 133 public function update_value( $meta, $object_id ) { 134 $fields = $this->get_registered_fields(); 135 foreach ( $fields as $meta_key => $args ) { 136 $name = $args['name']; 137 if ( ! array_key_exists( $name, $meta ) ) { 138 continue; 139 } 140 141 /* 142 * A null value means reset the field, which is essentially deleting it 143 * from the database and then relying on the default value. 144 */ 145 if ( is_null( $meta[ $name ] ) ) { 146 $args = $this->get_registered_fields()[ $meta_key ]; 147 148 if ( $args['single'] ) { 149 $current = get_metadata( $this->get_meta_type(), $object_id, $meta_key, true ); 150 151 if ( is_wp_error( rest_validate_value_from_schema( $current, $args['schema'] ) ) ) { 152 return new WP_Error( 153 'rest_invalid_stored_value', 154 /* translators: %s: Custom field key. */ 155 sprintf( __( 'The %s property has an invalid stored value, and cannot be updated to null.' ), $name ), 156 array( 'status' => 500 ) 157 ); 158 } 159 } 160 161 $result = $this->delete_meta_value( $object_id, $meta_key, $name ); 162 if ( is_wp_error( $result ) ) { 163 return $result; 164 } 165 continue; 166 } 167 168 $value = $meta[ $name ]; 169 170 if ( ! $args['single'] && is_array( $value ) && count( array_filter( $value, 'is_null' ) ) ) { 171 return new WP_Error( 172 'rest_invalid_stored_value', 173 /* translators: %s: Custom field key. */ 174 sprintf( __( 'The %s property has an invalid stored value, and cannot be updated to null.' ), $name ), 175 array( 'status' => 500 ) 176 ); 177 } 178 179 $is_valid = rest_validate_value_from_schema( $value, $args['schema'], 'meta.' . $name ); 180 if ( is_wp_error( $is_valid ) ) { 181 $is_valid->add_data( array( 'status' => 400 ) ); 182 return $is_valid; 183 } 184 185 $value = rest_sanitize_value_from_schema( $value, $args['schema'] ); 186 187 if ( $args['single'] ) { 188 $result = $this->update_meta_value( $object_id, $meta_key, $name, $value ); 189 } else { 190 $result = $this->update_multi_meta_value( $object_id, $meta_key, $name, $value ); 191 } 192 193 if ( is_wp_error( $result ) ) { 194 return $result; 195 } 196 } 197 198 return null; 199 } 200 201 /** 202 * Deletes a meta value for an object. 203 * 204 * @since 4.7.0 205 * 206 * @param int $object_id Object ID the field belongs to. 207 * @param string $meta_key Key for the field. 208 * @param string $name Name for the field that is exposed in the REST API. 209 * @return bool|WP_Error True if meta field is deleted, WP_Error otherwise. 210 */ 211 protected function delete_meta_value( $object_id, $meta_key, $name ) { 212 $meta_type = $this->get_meta_type(); 213 if ( ! current_user_can( "delete_{$meta_type}_meta", $object_id, $meta_key ) ) { 214 return new WP_Error( 215 'rest_cannot_delete', 216 /* translators: %s: Custom field key. */ 217 sprintf( __( 'Sorry, you are not allowed to edit the %s custom field.' ), $name ), 218 array( 219 'key' => $name, 220 'status' => rest_authorization_required_code(), 221 ) 222 ); 223 } 224 225 if ( ! delete_metadata( $meta_type, $object_id, wp_slash( $meta_key ) ) ) { 226 return new WP_Error( 227 'rest_meta_database_error', 228 __( 'Could not delete meta value from database.' ), 229 array( 230 'key' => $name, 231 'status' => WP_Http::INTERNAL_SERVER_ERROR, 232 ) 233 ); 234 } 235 236 return true; 237 } 238 239 /** 240 * Updates multiple meta values for an object. 241 * 242 * Alters the list of values in the database to match the list of provided values. 243 * 244 * @since 4.7.0 245 * 246 * @param int $object_id Object ID to update. 247 * @param string $meta_key Key for the custom field. 248 * @param string $name Name for the field that is exposed in the REST API. 249 * @param array $values List of values to update to. 250 * @return bool|WP_Error True if meta fields are updated, WP_Error otherwise. 251 */ 252 protected function update_multi_meta_value( $object_id, $meta_key, $name, $values ) { 253 $meta_type = $this->get_meta_type(); 254 if ( ! current_user_can( "edit_{$meta_type}_meta", $object_id, $meta_key ) ) { 255 return new WP_Error( 256 'rest_cannot_update', 257 /* translators: %s: Custom field key. */ 258 sprintf( __( 'Sorry, you are not allowed to edit the %s custom field.' ), $name ), 259 array( 260 'key' => $name, 261 'status' => rest_authorization_required_code(), 262 ) 263 ); 264 } 265 266 $current = get_metadata( $meta_type, $object_id, $meta_key, false ); 267 268 $to_remove = $current; 269 $to_add = $values; 270 271 foreach ( $to_add as $add_key => $value ) { 272 $remove_keys = array_keys( $to_remove, $value, true ); 273 274 if ( empty( $remove_keys ) ) { 275 continue; 276 } 277 278 if ( count( $remove_keys ) > 1 ) { 279 // To remove, we need to remove first, then add, so don't touch. 280 continue; 281 } 282 283 $remove_key = $remove_keys[0]; 284 285 unset( $to_remove[ $remove_key ] ); 286 unset( $to_add[ $add_key ] ); 287 } 288 289 // `delete_metadata` removes _all_ instances of the value, so only call once. Otherwise, 290 // `delete_metadata` will return false for subsequent calls of the same value. 291 // Use serialization to produce a predictable string that can be used by array_unique. 292 $to_remove = array_map( 'maybe_unserialize', array_unique( array_map( 'maybe_serialize', $to_remove ) ) ); 293 294 foreach ( $to_remove as $value ) { 295 if ( ! delete_metadata( $meta_type, $object_id, wp_slash( $meta_key ), wp_slash( $value ) ) ) { 296 return new WP_Error( 297 'rest_meta_database_error', 298 /* translators: %s: Custom field key. */ 299 sprintf( __( 'Could not update the meta value of %s in database.' ), $meta_key ), 300 array( 301 'key' => $name, 302 'status' => WP_Http::INTERNAL_SERVER_ERROR, 303 ) 304 ); 305 } 306 } 307 308 foreach ( $to_add as $value ) { 309 if ( ! add_metadata( $meta_type, $object_id, wp_slash( $meta_key ), wp_slash( $value ) ) ) { 310 return new WP_Error( 311 'rest_meta_database_error', 312 /* translators: %s: Custom field key. */ 313 sprintf( __( 'Could not update the meta value of %s in database.' ), $meta_key ), 314 array( 315 'key' => $name, 316 'status' => WP_Http::INTERNAL_SERVER_ERROR, 317 ) 318 ); 319 } 320 } 321 322 return true; 323 } 324 325 /** 326 * Updates a meta value for an object. 327 * 328 * @since 4.7.0 329 * 330 * @param int $object_id Object ID to update. 331 * @param string $meta_key Key for the custom field. 332 * @param string $name Name for the field that is exposed in the REST API. 333 * @param mixed $value Updated value. 334 * @return bool|WP_Error True if the meta field was updated, WP_Error otherwise. 335 */ 336 protected function update_meta_value( $object_id, $meta_key, $name, $value ) { 337 $meta_type = $this->get_meta_type(); 338 if ( ! current_user_can( "edit_{$meta_type}_meta", $object_id, $meta_key ) ) { 339 return new WP_Error( 340 'rest_cannot_update', 341 /* translators: %s: Custom field key. */ 342 sprintf( __( 'Sorry, you are not allowed to edit the %s custom field.' ), $name ), 343 array( 344 'key' => $name, 345 'status' => rest_authorization_required_code(), 346 ) 347 ); 348 } 349 350 // Do the exact same check for a duplicate value as in update_metadata() to avoid update_metadata() returning false. 351 $old_value = get_metadata( $meta_type, $object_id, $meta_key ); 352 $subtype = get_object_subtype( $meta_type, $object_id ); 353 $args = $this->get_registered_fields()[ $meta_key ]; 354 355 if ( 1 === count( $old_value ) ) { 356 $sanitized = sanitize_meta( $meta_key, $value, $meta_type, $subtype ); 357 358 if ( in_array( $args['type'], array( 'string', 'number', 'integer', 'boolean' ), true ) ) { 359 // The return value of get_metadata will always be a string for scalar types. 360 $sanitized = (string) $sanitized; 361 } 362 363 if ( $sanitized === $old_value[0] ) { 364 return true; 365 } 366 } 367 368 if ( ! update_metadata( $meta_type, $object_id, wp_slash( $meta_key ), wp_slash_strings_only( $value ) ) ) { 369 return new WP_Error( 370 'rest_meta_database_error', 371 /* translators: %s: Custom field key. */ 372 sprintf( __( 'Could not update the meta value of %s in database.' ), $meta_key ), 373 array( 374 'key' => $name, 375 'status' => WP_Http::INTERNAL_SERVER_ERROR, 376 ) 377 ); 378 } 379 380 return true; 381 } 382 383 /** 384 * Retrieves all the registered meta fields. 385 * 386 * @since 4.7.0 387 * 388 * @return array Registered fields. 389 */ 390 protected function get_registered_fields() { 391 $registered = array(); 392 393 $meta_type = $this->get_meta_type(); 394 $meta_subtype = $this->get_meta_subtype(); 395 396 $meta_keys = get_registered_meta_keys( $meta_type ); 397 if ( ! empty( $meta_subtype ) ) { 398 $meta_keys = array_merge( $meta_keys, get_registered_meta_keys( $meta_type, $meta_subtype ) ); 399 } 400 401 foreach ( $meta_keys as $name => $args ) { 402 if ( empty( $args['show_in_rest'] ) ) { 403 continue; 404 } 405 406 $rest_args = array(); 407 408 if ( is_array( $args['show_in_rest'] ) ) { 409 $rest_args = $args['show_in_rest']; 410 } 411 412 $default_args = array( 413 'name' => $name, 414 'single' => $args['single'], 415 'type' => ! empty( $args['type'] ) ? $args['type'] : null, 416 'schema' => array(), 417 'prepare_callback' => array( $this, 'prepare_value' ), 418 ); 419 420 $default_schema = array( 421 'type' => $default_args['type'], 422 'description' => empty( $args['description'] ) ? '' : $args['description'], 423 'default' => isset( $args['default'] ) ? $args['default'] : null, 424 ); 425 426 $rest_args = array_merge( $default_args, $rest_args ); 427 $rest_args['schema'] = array_merge( $default_schema, $rest_args['schema'] ); 428 429 $type = ! empty( $rest_args['type'] ) ? $rest_args['type'] : null; 430 $type = ! empty( $rest_args['schema']['type'] ) ? $rest_args['schema']['type'] : $type; 431 432 if ( null === $rest_args['schema']['default'] ) { 433 $rest_args['schema']['default'] = static::get_empty_value_for_type( $type ); 434 } 435 436 $rest_args['schema'] = $this->default_additional_properties_to_false( $rest_args['schema'] ); 437 438 if ( ! in_array( $type, array( 'string', 'boolean', 'integer', 'number', 'array', 'object' ), true ) ) { 439 continue; 440 } 441 442 if ( empty( $rest_args['single'] ) ) { 443 $rest_args['schema'] = array( 444 'type' => 'array', 445 'items' => $rest_args['schema'], 446 ); 447 } 448 449 $registered[ $name ] = $rest_args; 450 } 451 452 return $registered; 453 } 454 455 /** 456 * Retrieves the object's meta schema, conforming to JSON Schema. 457 * 458 * @since 4.7.0 459 * 460 * @return array Field schema data. 461 */ 462 public function get_field_schema() { 463 $fields = $this->get_registered_fields(); 464 465 $schema = array( 466 'description' => __( 'Meta fields.' ), 467 'type' => 'object', 468 'context' => array( 'view', 'edit' ), 469 'properties' => array(), 470 'arg_options' => array( 471 'sanitize_callback' => null, 472 'validate_callback' => array( $this, 'check_meta_is_array' ), 473 ), 474 ); 475 476 foreach ( $fields as $args ) { 477 $schema['properties'][ $args['name'] ] = $args['schema']; 478 } 479 480 return $schema; 481 } 482 483 /** 484 * Prepares a meta value for output. 485 * 486 * Default preparation for meta fields. Override by passing the 487 * `prepare_callback` in your `show_in_rest` options. 488 * 489 * @since 4.7.0 490 * 491 * @param mixed $value Meta value from the database. 492 * @param WP_REST_Request $request Request object. 493 * @param array $args REST-specific options for the meta key. 494 * @return mixed Value prepared for output. If a non-JsonSerializable object, null. 495 */ 496 public static function prepare_value( $value, $request, $args ) { 497 498 if ( $args['single'] ) { 499 $schema = $args['schema']; 500 } else { 501 $schema = $args['schema']['items']; 502 } 503 504 if ( '' === $value && in_array( $schema['type'], array( 'boolean', 'integer', 'number' ), true ) ) { 505 $value = static::get_empty_value_for_type( $schema['type'] ); 506 } 507 508 if ( is_wp_error( rest_validate_value_from_schema( $value, $schema ) ) ) { 509 return null; 510 } 511 512 return rest_sanitize_value_from_schema( $value, $schema ); 513 } 514 515 /** 516 * Check the 'meta' value of a request is an associative array. 517 * 518 * @since 4.7.0 519 * 520 * @param mixed $value The meta value submitted in the request. 521 * @param WP_REST_Request $request Full details about the request. 522 * @param string $param The parameter name. 523 * @return array|false The meta array, if valid, false otherwise. 524 */ 525 public function check_meta_is_array( $value, $request, $param ) { 526 if ( ! is_array( $value ) ) { 527 return false; 528 } 529 530 return $value; 531 } 532 533 /** 534 * Recursively add additionalProperties = false to all objects in a schema if no additionalProperties setting 535 * is specified. 536 * 537 * This is needed to restrict properties of objects in meta values to only 538 * registered items, as the REST API will allow additional properties by 539 * default. 540 * 541 * @since 5.3.0 542 * 543 * @param array $schema The schema array. 544 * @return array 545 */ 546 protected function default_additional_properties_to_false( $schema ) { 547 switch ( $schema['type'] ) { 548 case 'object': 549 foreach ( $schema['properties'] as $key => $child_schema ) { 550 $schema['properties'][ $key ] = $this->default_additional_properties_to_false( $child_schema ); 551 } 552 553 if ( ! isset( $schema['additionalProperties'] ) ) { 554 $schema['additionalProperties'] = false; 555 } 556 break; 557 case 'array': 558 $schema['items'] = $this->default_additional_properties_to_false( $schema['items'] ); 559 break; 560 } 561 562 return $schema; 563 } 564 565 /** 566 * Gets the empty value for a schema type. 567 * 568 * @since 5.3.0 569 * 570 * @param string $type The schema type. 571 * @return mixed 572 */ 573 protected static function get_empty_value_for_type( $type ) { 574 switch ( $type ) { 575 case 'string': 576 return ''; 577 case 'boolean': 578 return false; 579 case 'integer': 580 return 0; 581 case 'number': 582 return 0.0; 583 case 'array': 584 case 'object': 585 return array(); 586 default: 587 return null; 588 } 589 } 590 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Wed Jan 22 01:00:03 2020 | Cross-referenced by PHPXref 0.7.1 |