| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * REST API: WP_REST_Global_Styles_Controller class 4 * 5 * @package WordPress 6 * @subpackage REST_API 7 * @since 5.9.0 8 */ 9 10 /** 11 * Base Global Styles REST API Controller. 12 */ 13 class WP_REST_Global_Styles_Controller extends WP_REST_Posts_Controller { 14 /** 15 * Whether the controller supports batching. 16 * 17 * @since 6.6.0 18 * @var array 19 */ 20 protected $allow_batch = array( 'v1' => false ); 21 22 /** 23 * Constructor. 24 * 25 * @since 6.6.0 26 * 27 * @param string $post_type Post type. 28 */ 29 public function __construct( $post_type = 'wp_global_styles' ) { 30 parent::__construct( $post_type ); 31 } 32 33 /** 34 * Registers the controllers routes. 35 * 36 * @since 5.9.0 37 */ 38 public function register_routes() { 39 register_rest_route( 40 $this->namespace, 41 '/' . $this->rest_base . '/themes/(?P<stylesheet>[\/\s%\w\.\(\)\[\]\@_\-]+)/variations', 42 array( 43 array( 44 'methods' => WP_REST_Server::READABLE, 45 'callback' => array( $this, 'get_theme_items' ), 46 'permission_callback' => array( $this, 'get_theme_items_permissions_check' ), 47 'args' => array( 48 'stylesheet' => array( 49 'description' => __( 'The theme identifier' ), 50 'type' => 'string', 51 ), 52 ), 53 'allow_batch' => $this->allow_batch, 54 ), 55 ) 56 ); 57 58 // List themes global styles. 59 register_rest_route( 60 $this->namespace, 61 // The route. 62 sprintf( 63 '/%s/themes/(?P<stylesheet>%s)', 64 $this->rest_base, 65 /* 66 * Matches theme's directory: `/themes/<subdirectory>/<theme>/` or `/themes/<theme>/`. 67 * Excludes invalid directory name characters: `/:<>*?"|`. 68 */ 69 '[^\/:<>\*\?"\|]+(?:\/[^\/:<>\*\?"\|]+)?' 70 ), 71 array( 72 array( 73 'methods' => WP_REST_Server::READABLE, 74 'callback' => array( $this, 'get_theme_item' ), 75 'permission_callback' => array( $this, 'get_theme_item_permissions_check' ), 76 'args' => array( 77 'stylesheet' => array( 78 'description' => __( 'The theme identifier' ), 79 'type' => 'string', 80 'sanitize_callback' => array( $this, '_sanitize_global_styles_callback' ), 81 ), 82 ), 83 'allow_batch' => $this->allow_batch, 84 ), 85 ) 86 ); 87 88 // Lists/updates a single global style variation based on the given id. 89 register_rest_route( 90 $this->namespace, 91 '/' . $this->rest_base . '/(?P<id>[\/\d+]+)', 92 array( 93 array( 94 'methods' => WP_REST_Server::READABLE, 95 'callback' => array( $this, 'get_item' ), 96 'permission_callback' => array( $this, 'get_item_permissions_check' ), 97 'args' => array( 98 'id' => array( 99 'description' => __( 'ID of global styles config.' ), 100 'type' => 'integer', 101 ), 102 ), 103 ), 104 array( 105 'methods' => WP_REST_Server::EDITABLE, 106 'callback' => array( $this, 'update_item' ), 107 'permission_callback' => array( $this, 'update_item_permissions_check' ), 108 'args' => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ), 109 ), 110 'schema' => array( $this, 'get_public_item_schema' ), 111 'allow_batch' => $this->allow_batch, 112 ) 113 ); 114 } 115 116 /** 117 * Sanitize the global styles stylesheet to decode endpoint. 118 * For example, `wp/v2/global-styles/twentytwentytwo%200.4.0` 119 * would be decoded to `twentytwentytwo 0.4.0`. 120 * 121 * @since 5.9.0 122 * 123 * @param string $stylesheet Global styles stylesheet. 124 * @return string Sanitized global styles stylesheet. 125 */ 126 public function _sanitize_global_styles_callback( $stylesheet ) { 127 return urldecode( $stylesheet ); 128 } 129 130 /** 131 * Get the post, if the ID is valid. 132 * 133 * @since 5.9.0 134 * 135 * @param int $id Supplied ID. 136 * @return WP_Post|WP_Error Post object if ID is valid, WP_Error otherwise. 137 */ 138 protected function get_post( $id ) { 139 $error = new WP_Error( 140 'rest_global_styles_not_found', 141 __( 'No global styles config exists with that ID.' ), 142 array( 'status' => 404 ) 143 ); 144 145 $id = (int) $id; 146 if ( $id <= 0 ) { 147 return $error; 148 } 149 150 $post = get_post( $id ); 151 if ( empty( $post ) || empty( $post->ID ) || $this->post_type !== $post->post_type ) { 152 return $error; 153 } 154 155 return $post; 156 } 157 158 /** 159 * Checks if a given request has access to read a single global style. 160 * 161 * @since 5.9.0 162 * 163 * @param WP_REST_Request $request Full details about the request. 164 * @return true|WP_Error True if the request has read access, WP_Error object otherwise. 165 */ 166 public function get_item_permissions_check( $request ) { 167 $post = $this->get_post( $request['id'] ); 168 if ( is_wp_error( $post ) ) { 169 return $post; 170 } 171 172 if ( 'edit' === $request['context'] && $post && ! $this->check_update_permission( $post ) ) { 173 return new WP_Error( 174 'rest_forbidden_context', 175 __( 'Sorry, you are not allowed to edit this global style.' ), 176 array( 'status' => rest_authorization_required_code() ) 177 ); 178 } 179 180 if ( ! $this->check_read_permission( $post ) ) { 181 return new WP_Error( 182 'rest_cannot_view', 183 __( 'Sorry, you are not allowed to view this global style.' ), 184 array( 'status' => rest_authorization_required_code() ) 185 ); 186 } 187 188 return true; 189 } 190 191 /** 192 * Checks if a global style can be read. 193 * 194 * @since 5.9.0 195 * 196 * @param WP_Post $post Post object. 197 * @return bool Whether the post can be read. 198 */ 199 public function check_read_permission( $post ) { 200 return current_user_can( 'read_post', $post->ID ); 201 } 202 203 /** 204 * Checks if a given request has access to write a single global styles config. 205 * 206 * @since 5.9.0 207 * 208 * @param WP_REST_Request $request Full details about the request. 209 * @return true|WP_Error True if the request has write access for the item, WP_Error object otherwise. 210 */ 211 public function update_item_permissions_check( $request ) { 212 $post = $this->get_post( $request['id'] ); 213 if ( is_wp_error( $post ) ) { 214 return $post; 215 } 216 217 if ( $post && ! $this->check_update_permission( $post ) ) { 218 return new WP_Error( 219 'rest_cannot_edit', 220 __( 'Sorry, you are not allowed to edit this global style.' ), 221 array( 'status' => rest_authorization_required_code() ) 222 ); 223 } 224 225 return true; 226 } 227 228 /** 229 * Prepares a single global styles config for update. 230 * 231 * @since 5.9.0 232 * @since 6.2.0 Added validation of styles.css property. 233 * @since 6.6.0 Added registration of block style variations from theme.json sources (theme.json, user theme.json, partials). 234 * 235 * @param WP_REST_Request $request Request object. 236 * @return stdClass|WP_Error Prepared item on success. WP_Error on when the custom CSS is not valid. 237 */ 238 protected function prepare_item_for_database( $request ) { 239 $changes = new stdClass(); 240 $changes->ID = $request['id']; 241 242 $post = get_post( $request['id'] ); 243 $existing_config = array(); 244 if ( $post ) { 245 $existing_config = json_decode( $post->post_content, true ); 246 $json_decoding_error = json_last_error(); 247 if ( JSON_ERROR_NONE !== $json_decoding_error || ! isset( $existing_config['isGlobalStylesUserThemeJSON'] ) || 248 ! $existing_config['isGlobalStylesUserThemeJSON'] ) { 249 $existing_config = array(); 250 } 251 } 252 253 if ( isset( $request['styles'] ) || isset( $request['settings'] ) ) { 254 $config = array(); 255 if ( isset( $request['styles'] ) ) { 256 if ( isset( $request['styles']['css'] ) ) { 257 $css_validation_result = $this->validate_custom_css( $request['styles']['css'] ); 258 if ( is_wp_error( $css_validation_result ) ) { 259 return $css_validation_result; 260 } 261 } 262 $config['styles'] = $request['styles']; 263 } elseif ( isset( $existing_config['styles'] ) ) { 264 $config['styles'] = $existing_config['styles']; 265 } 266 267 // Register theme-defined variations e.g. from block style variation partials under `/styles`. 268 $variations = WP_Theme_JSON_Resolver::get_style_variations( 'block' ); 269 wp_register_block_style_variations_from_theme_json_partials( $variations ); 270 271 if ( isset( $request['settings'] ) ) { 272 $config['settings'] = $request['settings']; 273 } elseif ( isset( $existing_config['settings'] ) ) { 274 $config['settings'] = $existing_config['settings']; 275 } 276 $config['isGlobalStylesUserThemeJSON'] = true; 277 $config['version'] = WP_Theme_JSON::LATEST_SCHEMA; 278 $changes->post_content = wp_json_encode( $config ); 279 } 280 281 // Post title. 282 if ( isset( $request['title'] ) ) { 283 if ( is_string( $request['title'] ) ) { 284 $changes->post_title = $request['title']; 285 } elseif ( ! empty( $request['title']['raw'] ) ) { 286 $changes->post_title = $request['title']['raw']; 287 } 288 } 289 290 return $changes; 291 } 292 293 /** 294 * Prepare a global styles config output for response. 295 * 296 * @since 5.9.0 297 * @since 6.6.0 Added custom relative theme file URIs to `_links`. 298 * 299 * @param WP_Post $post Global Styles post object. 300 * @param WP_REST_Request $request Request object. 301 * @return WP_REST_Response Response object. 302 */ 303 public function prepare_item_for_response( $post, $request ) { 304 $raw_config = json_decode( $post->post_content, true ); 305 $is_global_styles_user_theme_json = isset( $raw_config['isGlobalStylesUserThemeJSON'] ) && true === $raw_config['isGlobalStylesUserThemeJSON']; 306 $config = array(); 307 $theme_json = null; 308 if ( $is_global_styles_user_theme_json ) { 309 $theme_json = new WP_Theme_JSON( $raw_config, 'custom' ); 310 $config = $theme_json->get_raw_data(); 311 } 312 313 // Base fields for every post. 314 $fields = $this->get_fields_for_response( $request ); 315 $data = array(); 316 317 if ( rest_is_field_included( 'id', $fields ) ) { 318 $data['id'] = $post->ID; 319 } 320 321 if ( rest_is_field_included( 'title', $fields ) ) { 322 $data['title'] = array(); 323 } 324 if ( rest_is_field_included( 'title.raw', $fields ) ) { 325 $data['title']['raw'] = $post->post_title; 326 } 327 if ( rest_is_field_included( 'title.rendered', $fields ) ) { 328 add_filter( 'protected_title_format', array( $this, 'protected_title_format' ) ); 329 add_filter( 'private_title_format', array( $this, 'protected_title_format' ) ); 330 331 $data['title']['rendered'] = get_the_title( $post->ID ); 332 333 remove_filter( 'protected_title_format', array( $this, 'protected_title_format' ) ); 334 remove_filter( 'private_title_format', array( $this, 'protected_title_format' ) ); 335 } 336 337 if ( rest_is_field_included( 'settings', $fields ) ) { 338 $data['settings'] = ! empty( $config['settings'] ) && $is_global_styles_user_theme_json ? $config['settings'] : new stdClass(); 339 } 340 341 if ( rest_is_field_included( 'styles', $fields ) ) { 342 $data['styles'] = ! empty( $config['styles'] ) && $is_global_styles_user_theme_json ? $config['styles'] : new stdClass(); 343 } 344 345 $context = ! empty( $request['context'] ) ? $request['context'] : 'view'; 346 $data = $this->add_additional_fields_to_object( $data, $request ); 347 $data = $this->filter_response_by_context( $data, $context ); 348 349 // Wrap the data in a response object. 350 $response = rest_ensure_response( $data ); 351 352 if ( rest_is_field_included( '_links', $fields ) || rest_is_field_included( '_embedded', $fields ) ) { 353 $links = $this->prepare_links( $post->ID ); 354 355 // Only return resolved URIs for get requests to user theme JSON. 356 if ( $theme_json ) { 357 $resolved_theme_uris = WP_Theme_JSON_Resolver::get_resolved_theme_uris( $theme_json ); 358 if ( ! empty( $resolved_theme_uris ) ) { 359 $links['https://api.w.org/theme-file'] = $resolved_theme_uris; 360 } 361 } 362 363 $response->add_links( $links ); 364 if ( ! empty( $links['self']['href'] ) ) { 365 $actions = $this->get_available_actions( $post, $request ); 366 $self = $links['self']['href']; 367 foreach ( $actions as $rel ) { 368 $response->add_link( $rel, $self ); 369 } 370 } 371 } 372 373 return $response; 374 } 375 376 /** 377 * Prepares links for the request. 378 * 379 * @since 5.9.0 380 * @since 6.3.0 Adds revisions count and rest URL href to version-history. 381 * 382 * @param integer $id ID. 383 * @return array Links for the given post. 384 */ 385 protected function prepare_links( $id ) { 386 $base = sprintf( '%s/%s', $this->namespace, $this->rest_base ); 387 388 $links = array( 389 'self' => array( 390 'href' => rest_url( trailingslashit( $base ) . $id ), 391 ), 392 'about' => array( 393 'href' => rest_url( 'wp/v2/types/' . $this->post_type ), 394 ), 395 ); 396 397 if ( post_type_supports( $this->post_type, 'revisions' ) ) { 398 $revisions = wp_get_latest_revision_id_and_total_count( $id ); 399 $revisions_count = ! is_wp_error( $revisions ) ? $revisions['count'] : 0; 400 $revisions_base = sprintf( '/%s/%d/revisions', $base, $id ); 401 $links['version-history'] = array( 402 'href' => rest_url( $revisions_base ), 403 'count' => $revisions_count, 404 ); 405 } 406 407 return $links; 408 } 409 410 /** 411 * Get the link relations available for the post and current user. 412 * 413 * @since 5.9.0 414 * @since 6.2.0 Added 'edit-css' action. 415 * @since 6.6.0 Added $post and $request parameters. 416 * 417 * @param WP_Post $post Post object. 418 * @param WP_REST_Request $request Request object. 419 * @return array List of link relations. 420 */ 421 protected function get_available_actions( $post, $request ) { 422 $rels = array(); 423 424 $post_type = get_post_type_object( $post->post_type ); 425 if ( current_user_can( $post_type->cap->publish_posts ) ) { 426 $rels[] = 'https://api.w.org/action-publish'; 427 } 428 429 if ( current_user_can( 'edit_css' ) ) { 430 $rels[] = 'https://api.w.org/action-edit-css'; 431 } 432 433 return $rels; 434 } 435 436 /** 437 * Retrieves the query params for the global styles collection. 438 * 439 * @since 5.9.0 440 * 441 * @return array Collection parameters. 442 */ 443 public function get_collection_params() { 444 return array(); 445 } 446 447 /** 448 * Retrieves the global styles type' schema, conforming to JSON Schema. 449 * 450 * @since 5.9.0 451 * 452 * @return array Item schema data. 453 */ 454 public function get_item_schema() { 455 if ( $this->schema ) { 456 return $this->add_additional_fields_schema( $this->schema ); 457 } 458 459 $schema = array( 460 '$schema' => 'http://json-schema.org/draft-04/schema#', 461 'title' => $this->post_type, 462 'type' => 'object', 463 'properties' => array( 464 'id' => array( 465 'description' => __( 'ID of global styles config.' ), 466 'type' => 'integer', 467 'context' => array( 'embed', 'view', 'edit' ), 468 'readonly' => true, 469 ), 470 'styles' => array( 471 'description' => __( 'Global styles.' ), 472 'type' => array( 'object' ), 473 'context' => array( 'view', 'edit' ), 474 ), 475 'settings' => array( 476 'description' => __( 'Global settings.' ), 477 'type' => array( 'object' ), 478 'context' => array( 'view', 'edit' ), 479 ), 480 'title' => array( 481 'description' => __( 'Title of the global styles variation.' ), 482 'type' => array( 'object', 'string' ), 483 'default' => '', 484 'context' => array( 'embed', 'view', 'edit' ), 485 'properties' => array( 486 'raw' => array( 487 'description' => __( 'Title for the global styles variation, as it exists in the database.' ), 488 'type' => 'string', 489 'context' => array( 'view', 'edit', 'embed' ), 490 ), 491 'rendered' => array( 492 'description' => __( 'HTML title for the post, transformed for display.' ), 493 'type' => 'string', 494 'context' => array( 'view', 'edit', 'embed' ), 495 'readonly' => true, 496 ), 497 ), 498 ), 499 ), 500 ); 501 502 $this->schema = $schema; 503 504 return $this->add_additional_fields_schema( $this->schema ); 505 } 506 507 /** 508 * Checks if a given request has access to read a single theme global styles config. 509 * 510 * @since 5.9.0 511 * @since 6.7.0 Allow users with edit post capabilities to view theme global styles. 512 * 513 * @param WP_REST_Request $request Full details about the request. 514 * @return true|WP_Error True if the request has read access for the item, WP_Error object otherwise. 515 */ 516 public function get_theme_item_permissions_check( $request ) { 517 /* 518 * Verify if the current user has edit_posts capability. 519 * This capability is required to view global styles. 520 */ 521 if ( current_user_can( 'edit_posts' ) ) { 522 return true; 523 } 524 525 foreach ( get_post_types( array( 'show_in_rest' => true ), 'objects' ) as $post_type ) { 526 if ( current_user_can( $post_type->cap->edit_posts ) ) { 527 return true; 528 } 529 } 530 531 /* 532 * Verify if the current user has edit_theme_options capability. 533 */ 534 if ( current_user_can( 'edit_theme_options' ) ) { 535 return true; 536 } 537 538 return new WP_Error( 539 'rest_cannot_read_global_styles', 540 __( 'Sorry, you are not allowed to access the global styles on this site.' ), 541 array( 542 'status' => rest_authorization_required_code(), 543 ) 544 ); 545 } 546 547 /** 548 * Returns the given theme global styles config. 549 * 550 * @since 5.9.0 551 * @since 6.6.0 Added custom relative theme file URIs to `_links`. 552 * 553 * @param WP_REST_Request $request The request instance. 554 * @return WP_REST_Response|WP_Error 555 */ 556 public function get_theme_item( $request ) { 557 if ( get_stylesheet() !== $request['stylesheet'] ) { 558 // This endpoint only supports the active theme for now. 559 return new WP_Error( 560 'rest_theme_not_found', 561 __( 'Theme not found.' ), 562 array( 'status' => 404 ) 563 ); 564 } 565 566 $theme = WP_Theme_JSON_Resolver::get_merged_data( 'theme' ); 567 $fields = $this->get_fields_for_response( $request ); 568 $data = array(); 569 570 if ( rest_is_field_included( 'settings', $fields ) ) { 571 $data['settings'] = $theme->get_settings(); 572 } 573 574 if ( rest_is_field_included( 'styles', $fields ) ) { 575 $raw_data = $theme->get_raw_data(); 576 $data['styles'] = isset( $raw_data['styles'] ) ? $raw_data['styles'] : array(); 577 } 578 579 $context = ! empty( $request['context'] ) ? $request['context'] : 'view'; 580 $data = $this->add_additional_fields_to_object( $data, $request ); 581 $data = $this->filter_response_by_context( $data, $context ); 582 583 $response = rest_ensure_response( $data ); 584 585 if ( rest_is_field_included( '_links', $fields ) || rest_is_field_included( '_embedded', $fields ) ) { 586 $links = array( 587 'self' => array( 588 'href' => rest_url( sprintf( '%s/%s/themes/%s', $this->namespace, $this->rest_base, $request['stylesheet'] ) ), 589 ), 590 ); 591 $resolved_theme_uris = WP_Theme_JSON_Resolver::get_resolved_theme_uris( $theme ); 592 if ( ! empty( $resolved_theme_uris ) ) { 593 $links['https://api.w.org/theme-file'] = $resolved_theme_uris; 594 } 595 $response->add_links( $links ); 596 } 597 598 return $response; 599 } 600 601 /** 602 * Checks if a given request has access to read a single theme global styles config. 603 * 604 * @since 6.0.0 605 * @since 6.7.0 Allow users with edit post capabilities to view theme global styles. 606 * 607 * @param WP_REST_Request $request Full details about the request. 608 * @return true|WP_Error True if the request has read access for the item, WP_Error object otherwise. 609 */ 610 public function get_theme_items_permissions_check( $request ) { 611 return $this->get_theme_item_permissions_check( $request ); 612 } 613 614 /** 615 * Returns the given theme global styles variations. 616 * 617 * @since 6.0.0 618 * @since 6.2.0 Returns parent theme variations, if they exist. 619 * @since 6.6.0 Added custom relative theme file URIs to `_links` for each item. 620 * 621 * @param WP_REST_Request $request The request instance. 622 * 623 * @return WP_REST_Response|WP_Error 624 */ 625 public function get_theme_items( $request ) { 626 if ( get_stylesheet() !== $request['stylesheet'] ) { 627 // This endpoint only supports the active theme for now. 628 return new WP_Error( 629 'rest_theme_not_found', 630 __( 'Theme not found.' ), 631 array( 'status' => 404 ) 632 ); 633 } 634 635 $response = array(); 636 637 // Register theme-defined variations e.g. from block style variation partials under `/styles`. 638 $partials = WP_Theme_JSON_Resolver::get_style_variations( 'block' ); 639 wp_register_block_style_variations_from_theme_json_partials( $partials ); 640 641 $variations = WP_Theme_JSON_Resolver::get_style_variations(); 642 foreach ( $variations as $variation ) { 643 $variation_theme_json = new WP_Theme_JSON( $variation ); 644 $resolved_theme_uris = WP_Theme_JSON_Resolver::get_resolved_theme_uris( $variation_theme_json ); 645 $data = rest_ensure_response( $variation ); 646 if ( ! empty( $resolved_theme_uris ) ) { 647 $data->add_links( 648 array( 649 'https://api.w.org/theme-file' => $resolved_theme_uris, 650 ) 651 ); 652 } 653 $response[] = $this->prepare_response_for_collection( $data ); 654 } 655 656 return rest_ensure_response( $response ); 657 } 658 659 /** 660 * Validate style.css as valid CSS. 661 * 662 * Currently just checks for invalid markup. 663 * 664 * @since 6.2.0 665 * @since 6.4.0 Changed method visibility to protected. 666 * 667 * @param string $css CSS to validate. 668 * @return true|WP_Error True if the input was validated, otherwise WP_Error. 669 */ 670 protected function validate_custom_css( $css ) { 671 if ( preg_match( '#</?\w+#', $css ) ) { 672 return new WP_Error( 673 'rest_custom_css_illegal_markup', 674 __( 'Markup is not allowed in CSS.' ), 675 array( 'status' => 400 ) 676 ); 677 } 678 return true; 679 } 680 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Tue Jul 1 08:20:01 2025 | Cross-referenced by PHPXref |