| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * REST API: WP_REST_Themes_Controller class 4 * 5 * @package WordPress 6 * @subpackage REST_API 7 * @since 5.0.0 8 */ 9 10 /** 11 * Core class used to manage themes via the REST API. 12 * 13 * @since 5.0.0 14 * 15 * @see WP_REST_Controller 16 */ 17 class WP_REST_Themes_Controller extends WP_REST_Controller { 18 19 /** 20 * Matches theme's directory: `/themes/<subdirectory>/<theme>/` or `/themes/<theme>/`. 21 * Excludes invalid directory name characters: `/:<>*?"|`. 22 */ 23 const PATTERN = '[^\/:<>\*\?"\|]+(?:\/[^\/:<>\*\?"\|]+)?'; 24 25 /** 26 * Constructor. 27 * 28 * @since 5.0.0 29 */ 30 public function __construct() { 31 $this->namespace = 'wp/v2'; 32 $this->rest_base = 'themes'; 33 } 34 35 /** 36 * Registers the routes for themes. 37 * 38 * @since 5.0.0 39 * 40 * @see register_rest_route() 41 */ 42 public function register_routes() { 43 register_rest_route( 44 $this->namespace, 45 '/' . $this->rest_base, 46 array( 47 array( 48 'methods' => WP_REST_Server::READABLE, 49 'callback' => array( $this, 'get_items' ), 50 'permission_callback' => array( $this, 'get_items_permissions_check' ), 51 'args' => $this->get_collection_params(), 52 ), 53 'schema' => array( $this, 'get_item_schema' ), 54 ) 55 ); 56 57 register_rest_route( 58 $this->namespace, 59 sprintf( '/%s/(?P<stylesheet>%s)', $this->rest_base, self::PATTERN ), 60 array( 61 'args' => array( 62 'stylesheet' => array( 63 'description' => __( "The theme's stylesheet. This uniquely identifies the theme." ), 64 'type' => 'string', 65 'sanitize_callback' => array( $this, '_sanitize_stylesheet_callback' ), 66 ), 67 ), 68 array( 69 'methods' => WP_REST_Server::READABLE, 70 'callback' => array( $this, 'get_item' ), 71 'permission_callback' => array( $this, 'get_item_permissions_check' ), 72 ), 73 'schema' => array( $this, 'get_public_item_schema' ), 74 ) 75 ); 76 } 77 78 /** 79 * Sanitize the stylesheet to decode endpoint. 80 * 81 * @since 5.9.0 82 * 83 * @param string $stylesheet The stylesheet name. 84 * @return string Sanitized stylesheet. 85 */ 86 public function _sanitize_stylesheet_callback( $stylesheet ) { 87 return urldecode( $stylesheet ); 88 } 89 90 /** 91 * Checks if a given request has access to read the theme. 92 * 93 * @since 5.0.0 94 * 95 * @param WP_REST_Request $request Full details about the request. 96 * @return true|WP_Error True if the request has read access for the item, otherwise WP_Error object. 97 */ 98 public function get_items_permissions_check( $request ) { 99 if ( current_user_can( 'switch_themes' ) || current_user_can( 'manage_network_themes' ) ) { 100 return true; 101 } 102 103 $registered = $this->get_collection_params(); 104 if ( isset( $registered['status'], $request['status'] ) && is_array( $request['status'] ) && array( 'active' ) === $request['status'] ) { 105 return $this->check_read_active_theme_permission(); 106 } 107 108 return new WP_Error( 109 'rest_cannot_view_themes', 110 __( 'Sorry, you are not allowed to view themes.' ), 111 array( 'status' => rest_authorization_required_code() ) 112 ); 113 } 114 115 /** 116 * Checks if a given request has access to read the theme. 117 * 118 * @since 5.7.0 119 * 120 * @param WP_REST_Request $request Full details about the request. 121 * @return true|WP_Error True if the request has read access for the item, otherwise WP_Error object. 122 */ 123 public function get_item_permissions_check( $request ) { 124 if ( current_user_can( 'switch_themes' ) || current_user_can( 'manage_network_themes' ) ) { 125 return true; 126 } 127 128 $wp_theme = wp_get_theme( $request['stylesheet'] ); 129 $current_theme = wp_get_theme(); 130 131 if ( $this->is_same_theme( $wp_theme, $current_theme ) ) { 132 return $this->check_read_active_theme_permission(); 133 } 134 135 return new WP_Error( 136 'rest_cannot_view_themes', 137 __( 'Sorry, you are not allowed to view themes.' ), 138 array( 'status' => rest_authorization_required_code() ) 139 ); 140 } 141 142 /** 143 * Checks if a theme can be read. 144 * 145 * @since 5.7.0 146 * 147 * @return true|WP_Error True if the theme can be read, WP_Error object otherwise. 148 */ 149 protected function check_read_active_theme_permission() { 150 if ( current_user_can( 'edit_posts' ) ) { 151 return true; 152 } 153 154 foreach ( get_post_types( array( 'show_in_rest' => true ), 'objects' ) as $post_type ) { 155 if ( current_user_can( $post_type->cap->edit_posts ) ) { 156 return true; 157 } 158 } 159 160 return new WP_Error( 161 'rest_cannot_view_active_theme', 162 __( 'Sorry, you are not allowed to view the active theme.' ), 163 array( 'status' => rest_authorization_required_code() ) 164 ); 165 } 166 167 /** 168 * Retrieves a single theme. 169 * 170 * @since 5.7.0 171 * 172 * @param WP_REST_Request $request Full details about the request. 173 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. 174 */ 175 public function get_item( $request ) { 176 $wp_theme = wp_get_theme( $request['stylesheet'] ); 177 if ( ! $wp_theme->exists() ) { 178 return new WP_Error( 179 'rest_theme_not_found', 180 __( 'Theme not found.' ), 181 array( 'status' => 404 ) 182 ); 183 } 184 $data = $this->prepare_item_for_response( $wp_theme, $request ); 185 186 return rest_ensure_response( $data ); 187 } 188 189 /** 190 * Retrieves a collection of themes. 191 * 192 * @since 5.0.0 193 * 194 * @param WP_REST_Request $request Full details about the request. 195 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. 196 */ 197 public function get_items( $request ) { 198 $themes = array(); 199 200 $active_themes = wp_get_themes(); 201 $current_theme = wp_get_theme(); 202 $status = $request['status']; 203 204 foreach ( $active_themes as $theme ) { 205 $theme_status = ( $this->is_same_theme( $theme, $current_theme ) ) ? 'active' : 'inactive'; 206 if ( is_array( $status ) && ! in_array( $theme_status, $status, true ) ) { 207 continue; 208 } 209 210 $prepared = $this->prepare_item_for_response( $theme, $request ); 211 $themes[] = $this->prepare_response_for_collection( $prepared ); 212 } 213 214 $response = rest_ensure_response( $themes ); 215 216 $response->header( 'X-WP-Total', count( $themes ) ); 217 $response->header( 'X-WP-TotalPages', 1 ); 218 219 return $response; 220 } 221 222 /** 223 * Prepares a single theme output for response. 224 * 225 * @since 5.0.0 226 * @since 5.9.0 Renamed `$theme` to `$item` to match parent class for PHP 8 named parameter support. 227 * @since 6.6.0 Added `stylesheet_uri` and `template_uri` fields. 228 * 229 * @param WP_Theme $item Theme object. 230 * @param WP_REST_Request $request Request object. 231 * @return WP_REST_Response Response object. 232 */ 233 public function prepare_item_for_response( $item, $request ) { 234 // Restores the more descriptive, specific name for use within this method. 235 $theme = $item; 236 237 $fields = $this->get_fields_for_response( $request ); 238 $data = array(); 239 240 if ( rest_is_field_included( 'stylesheet', $fields ) ) { 241 $data['stylesheet'] = $theme->get_stylesheet(); 242 } 243 244 if ( rest_is_field_included( 'template', $fields ) ) { 245 /** 246 * Use the get_template() method, not the 'Template' header, for finding the template. 247 * The 'Template' header is only good for what was written in the style.css, while 248 * get_template() takes into account where WordPress actually located the theme and 249 * whether it is actually valid. 250 */ 251 $data['template'] = $theme->get_template(); 252 } 253 254 $plain_field_mappings = array( 255 'requires_php' => 'RequiresPHP', 256 'requires_wp' => 'RequiresWP', 257 'textdomain' => 'TextDomain', 258 'version' => 'Version', 259 ); 260 261 foreach ( $plain_field_mappings as $field => $header ) { 262 if ( rest_is_field_included( $field, $fields ) ) { 263 $data[ $field ] = $theme->get( $header ); 264 } 265 } 266 267 if ( rest_is_field_included( 'screenshot', $fields ) ) { 268 // Using $theme->get_screenshot() with no args to get absolute URL. 269 $data['screenshot'] = $theme->get_screenshot() ? $theme->get_screenshot() : ''; 270 } 271 272 $rich_field_mappings = array( 273 'author' => 'Author', 274 'author_uri' => 'AuthorURI', 275 'description' => 'Description', 276 'name' => 'Name', 277 'tags' => 'Tags', 278 'theme_uri' => 'ThemeURI', 279 ); 280 281 foreach ( $rich_field_mappings as $field => $header ) { 282 if ( rest_is_field_included( "{$field}.raw", $fields ) ) { 283 $data[ $field ]['raw'] = $theme->display( $header, false, true ); 284 } 285 286 if ( rest_is_field_included( "{$field}.rendered", $fields ) ) { 287 $data[ $field ]['rendered'] = $theme->display( $header ); 288 } 289 } 290 291 $current_theme = wp_get_theme(); 292 if ( rest_is_field_included( 'status', $fields ) ) { 293 $data['status'] = ( $this->is_same_theme( $theme, $current_theme ) ) ? 'active' : 'inactive'; 294 } 295 296 if ( rest_is_field_included( 'theme_supports', $fields ) && $this->is_same_theme( $theme, $current_theme ) ) { 297 foreach ( get_registered_theme_features() as $feature => $config ) { 298 if ( ! is_array( $config['show_in_rest'] ) ) { 299 continue; 300 } 301 302 $name = $config['show_in_rest']['name']; 303 304 if ( ! rest_is_field_included( "theme_supports.{$name}", $fields ) ) { 305 continue; 306 } 307 308 if ( ! current_theme_supports( $feature ) ) { 309 $data['theme_supports'][ $name ] = $config['show_in_rest']['schema']['default']; 310 continue; 311 } 312 313 $support = get_theme_support( $feature ); 314 315 if ( isset( $config['show_in_rest']['prepare_callback'] ) ) { 316 $prepare = $config['show_in_rest']['prepare_callback']; 317 } else { 318 $prepare = array( $this, 'prepare_theme_support' ); 319 } 320 321 $prepared = $prepare( $support, $config, $feature, $request ); 322 323 if ( is_wp_error( $prepared ) ) { 324 continue; 325 } 326 327 $data['theme_supports'][ $name ] = $prepared; 328 } 329 } 330 331 if ( rest_is_field_included( 'is_block_theme', $fields ) ) { 332 $data['is_block_theme'] = $theme->is_block_theme(); 333 } 334 335 if ( rest_is_field_included( 'stylesheet_uri', $fields ) ) { 336 if ( $this->is_same_theme( $theme, $current_theme ) ) { 337 $data['stylesheet_uri'] = get_stylesheet_directory_uri(); 338 } else { 339 $data['stylesheet_uri'] = $theme->get_stylesheet_directory_uri(); 340 } 341 } 342 343 if ( rest_is_field_included( 'template_uri', $fields ) ) { 344 if ( $this->is_same_theme( $theme, $current_theme ) ) { 345 $data['template_uri'] = get_template_directory_uri(); 346 } else { 347 $data['template_uri'] = $theme->get_template_directory_uri(); 348 } 349 } 350 351 if ( rest_is_field_included( 'default_template_types', $fields ) && $this->is_same_theme( $theme, $current_theme ) ) { 352 $default_template_types = array(); 353 foreach ( get_default_block_template_types() as $slug => $template_type ) { 354 $template_type['slug'] = (string) $slug; 355 $default_template_types[] = $template_type; 356 } 357 $data['default_template_types'] = $default_template_types; 358 } 359 360 if ( rest_is_field_included( 'default_template_part_areas', $fields ) && $this->is_same_theme( $theme, $current_theme ) ) { 361 $data['default_template_part_areas'] = get_allowed_block_template_part_areas(); 362 } 363 364 $data = $this->add_additional_fields_to_object( $data, $request ); 365 366 // Wrap the data in a response object. 367 $response = rest_ensure_response( $data ); 368 369 if ( rest_is_field_included( '_links', $fields ) || rest_is_field_included( '_embedded', $fields ) ) { 370 $response->add_links( $this->prepare_links( $theme ) ); 371 } 372 373 /** 374 * Filters theme data returned from the REST API. 375 * 376 * @since 5.0.0 377 * 378 * @param WP_REST_Response $response The response object. 379 * @param WP_Theme $theme Theme object used to create response. 380 * @param WP_REST_Request $request Request object. 381 */ 382 return apply_filters( 'rest_prepare_theme', $response, $theme, $request ); 383 } 384 385 /** 386 * Prepares links for the request. 387 * 388 * @since 5.7.0 389 * 390 * @param WP_Theme $theme Theme data. 391 * @return array Links for the given block type. 392 */ 393 protected function prepare_links( $theme ) { 394 $links = array( 395 'self' => array( 396 'href' => rest_url( sprintf( '%s/%s/%s', $this->namespace, $this->rest_base, $theme->get_stylesheet() ) ), 397 ), 398 'collection' => array( 399 'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ), 400 ), 401 ); 402 403 if ( $this->is_same_theme( $theme, wp_get_theme() ) ) { 404 // This creates a record for the active theme if not existent. 405 $id = WP_Theme_JSON_Resolver::get_user_global_styles_post_id(); 406 } else { 407 $user_cpt = WP_Theme_JSON_Resolver::get_user_data_from_wp_global_styles( $theme ); 408 $id = isset( $user_cpt['ID'] ) ? $user_cpt['ID'] : null; 409 } 410 411 if ( $id ) { 412 $links['https://api.w.org/user-global-styles'] = array( 413 'href' => rest_url( 'wp/v2/global-styles/' . $id ), 414 ); 415 } 416 417 return $links; 418 } 419 420 /** 421 * Helper function to compare two themes. 422 * 423 * @since 5.7.0 424 * 425 * @param WP_Theme $theme_a First theme to compare. 426 * @param WP_Theme $theme_b Second theme to compare. 427 * @return bool 428 */ 429 protected function is_same_theme( $theme_a, $theme_b ) { 430 return $theme_a->get_stylesheet() === $theme_b->get_stylesheet(); 431 } 432 433 /** 434 * Prepares the theme support value for inclusion in the REST API response. 435 * 436 * @since 5.5.0 437 * 438 * @param mixed $support The raw value from get_theme_support(). 439 * @param array $args The feature's registration args. 440 * @param string $feature The feature name. 441 * @param WP_REST_Request $request The request object. 442 * @return mixed The prepared support value. 443 */ 444 protected function prepare_theme_support( $support, $args, $feature, $request ) { 445 $schema = $args['show_in_rest']['schema']; 446 447 if ( 'boolean' === $schema['type'] ) { 448 return true; 449 } 450 451 if ( is_array( $support ) && ! $args['variadic'] ) { 452 $support = $support[0]; 453 } 454 455 return rest_sanitize_value_from_schema( $support, $schema ); 456 } 457 458 /** 459 * Retrieves the theme's schema, conforming to JSON Schema. 460 * 461 * @since 5.0.0 462 * 463 * @return array Item schema data. 464 */ 465 public function get_item_schema() { 466 if ( $this->schema ) { 467 return $this->add_additional_fields_schema( $this->schema ); 468 } 469 470 $schema = array( 471 '$schema' => 'http://json-schema.org/draft-04/schema#', 472 'title' => 'theme', 473 'type' => 'object', 474 'properties' => array( 475 'stylesheet' => array( 476 'description' => __( 'The theme\'s stylesheet. This uniquely identifies the theme.' ), 477 'type' => 'string', 478 'readonly' => true, 479 ), 480 'stylesheet_uri' => array( 481 'description' => __( 'The uri for the theme\'s stylesheet directory.' ), 482 'type' => 'string', 483 'format' => 'uri', 484 'readonly' => true, 485 ), 486 'template' => array( 487 'description' => __( 'The theme\'s template. If this is a child theme, this refers to the parent theme, otherwise this is the same as the theme\'s stylesheet.' ), 488 'type' => 'string', 489 'readonly' => true, 490 ), 491 'template_uri' => array( 492 'description' => __( 'The uri for the theme\'s template directory. If this is a child theme, this refers to the parent theme, otherwise this is the same as the theme\'s stylesheet directory.' ), 493 'type' => 'string', 494 'format' => 'uri', 495 'readonly' => true, 496 ), 497 'author' => array( 498 'description' => __( 'The theme author.' ), 499 'type' => 'object', 500 'readonly' => true, 501 'properties' => array( 502 'raw' => array( 503 'description' => __( 'The theme author\'s name, as found in the theme header.' ), 504 'type' => 'string', 505 ), 506 'rendered' => array( 507 'description' => __( 'HTML for the theme author, transformed for display.' ), 508 'type' => 'string', 509 ), 510 ), 511 ), 512 'author_uri' => array( 513 'description' => __( 'The website of the theme author.' ), 514 'type' => 'object', 515 'readonly' => true, 516 'properties' => array( 517 'raw' => array( 518 'description' => __( 'The website of the theme author, as found in the theme header.' ), 519 'type' => 'string', 520 'format' => 'uri', 521 ), 522 'rendered' => array( 523 'description' => __( 'The website of the theme author, transformed for display.' ), 524 'type' => 'string', 525 'format' => 'uri', 526 ), 527 ), 528 ), 529 'description' => array( 530 'description' => __( 'A description of the theme.' ), 531 'type' => 'object', 532 'readonly' => true, 533 'properties' => array( 534 'raw' => array( 535 'description' => __( 'The theme description, as found in the theme header.' ), 536 'type' => 'string', 537 ), 538 'rendered' => array( 539 'description' => __( 'The theme description, transformed for display.' ), 540 'type' => 'string', 541 ), 542 ), 543 ), 544 'is_block_theme' => array( 545 'description' => __( 'Whether the theme is a block-based theme.' ), 546 'type' => 'boolean', 547 'readonly' => true, 548 ), 549 'name' => array( 550 'description' => __( 'The name of the theme.' ), 551 'type' => 'object', 552 'readonly' => true, 553 'properties' => array( 554 'raw' => array( 555 'description' => __( 'The theme name, as found in the theme header.' ), 556 'type' => 'string', 557 ), 558 'rendered' => array( 559 'description' => __( 'The theme name, transformed for display.' ), 560 'type' => 'string', 561 ), 562 ), 563 ), 564 'requires_php' => array( 565 'description' => __( 'The minimum PHP version required for the theme to work.' ), 566 'type' => 'string', 567 'readonly' => true, 568 ), 569 'requires_wp' => array( 570 'description' => __( 'The minimum WordPress version required for the theme to work.' ), 571 'type' => 'string', 572 'readonly' => true, 573 ), 574 'screenshot' => array( 575 'description' => __( 'The theme\'s screenshot URL.' ), 576 'type' => 'string', 577 'format' => 'uri', 578 'readonly' => true, 579 ), 580 'tags' => array( 581 'description' => __( 'Tags indicating styles and features of the theme.' ), 582 'type' => 'object', 583 'readonly' => true, 584 'properties' => array( 585 'raw' => array( 586 'description' => __( 'The theme tags, as found in the theme header.' ), 587 'type' => 'array', 588 'items' => array( 589 'type' => 'string', 590 ), 591 ), 592 'rendered' => array( 593 'description' => __( 'The theme tags, transformed for display.' ), 594 'type' => 'string', 595 ), 596 ), 597 ), 598 'textdomain' => array( 599 'description' => __( 'The theme\'s text domain.' ), 600 'type' => 'string', 601 'readonly' => true, 602 ), 603 'theme_supports' => array( 604 'description' => __( 'Features supported by this theme.' ), 605 'type' => 'object', 606 'readonly' => true, 607 'properties' => array(), 608 ), 609 'theme_uri' => array( 610 'description' => __( 'The URI of the theme\'s webpage.' ), 611 'type' => 'object', 612 'readonly' => true, 613 'properties' => array( 614 'raw' => array( 615 'description' => __( 'The URI of the theme\'s webpage, as found in the theme header.' ), 616 'type' => 'string', 617 'format' => 'uri', 618 ), 619 'rendered' => array( 620 'description' => __( 'The URI of the theme\'s webpage, transformed for display.' ), 621 'type' => 'string', 622 'format' => 'uri', 623 ), 624 ), 625 ), 626 'version' => array( 627 'description' => __( 'The theme\'s current version.' ), 628 'type' => 'string', 629 'readonly' => true, 630 ), 631 'status' => array( 632 'description' => __( 'A named status for the theme.' ), 633 'type' => 'string', 634 'enum' => array( 'inactive', 'active' ), 635 ), 636 'default_template_types' => array( 637 'description' => __( 'A list of default template types.' ), 638 'type' => 'array', 639 'readonly' => true, 640 'items' => array( 641 'type' => 'object', 642 'properties' => array( 643 'slug' => array( 644 'type' => 'string', 645 ), 646 'title' => array( 647 'type' => 'string', 648 ), 649 'description' => array( 650 'type' => 'string', 651 ), 652 ), 653 ), 654 ), 655 'default_template_part_areas' => array( 656 'description' => __( 'A list of allowed area values for template parts.' ), 657 'type' => 'array', 658 'readonly' => true, 659 'items' => array( 660 'type' => 'object', 661 'properties' => array( 662 'area' => array( 663 'type' => 'string', 664 ), 665 'label' => array( 666 'type' => 'string', 667 ), 668 'description' => array( 669 'type' => 'string', 670 ), 671 'icon' => array( 672 'type' => 'string', 673 ), 674 'area_tag' => array( 675 'type' => 'string', 676 ), 677 ), 678 ), 679 ), 680 ), 681 ); 682 683 foreach ( get_registered_theme_features() as $feature => $config ) { 684 if ( ! is_array( $config['show_in_rest'] ) ) { 685 continue; 686 } 687 688 $name = $config['show_in_rest']['name']; 689 690 $schema['properties']['theme_supports']['properties'][ $name ] = $config['show_in_rest']['schema']; 691 } 692 693 $this->schema = $schema; 694 695 return $this->add_additional_fields_schema( $this->schema ); 696 } 697 698 /** 699 * Retrieves the search params for the themes collection. 700 * 701 * @since 5.0.0 702 * 703 * @return array Collection parameters. 704 */ 705 public function get_collection_params() { 706 $query_params = array( 707 'status' => array( 708 'description' => __( 'Limit result set to themes assigned one or more statuses.' ), 709 'type' => 'array', 710 'items' => array( 711 'enum' => array( 'active', 'inactive' ), 712 'type' => 'string', 713 ), 714 ), 715 ); 716 717 /** 718 * Filters REST API collection parameters for the themes controller. 719 * 720 * @since 5.0.0 721 * 722 * @param array $query_params JSON Schema-formatted collection parameters. 723 */ 724 return apply_filters( 'rest_themes_collection_params', $query_params ); 725 } 726 727 /** 728 * Sanitizes and validates the list of theme status. 729 * 730 * @since 5.0.0 731 * @deprecated 5.7.0 732 * 733 * @param string|array $statuses One or more theme statuses. 734 * @param WP_REST_Request $request Full details about the request. 735 * @param string $parameter Additional parameter to pass to validation. 736 * @return array|WP_Error A list of valid statuses, otherwise WP_Error object. 737 */ 738 public function sanitize_theme_status( $statuses, $request, $parameter ) { 739 _deprecated_function( __METHOD__, '5.7.0' ); 740 741 $statuses = wp_parse_slug_list( $statuses ); 742 743 foreach ( $statuses as $status ) { 744 $result = rest_validate_request_arg( $status, $request, $parameter ); 745 746 if ( is_wp_error( $result ) ) { 747 return $result; 748 } 749 } 750 751 return $statuses; 752 } 753 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Thu Apr 24 08:20:01 2025 | Cross-referenced by PHPXref |