| [ 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 $data = $this->add_additional_fields_to_object( $data, $request ); 352 353 // Wrap the data in a response object. 354 $response = rest_ensure_response( $data ); 355 356 if ( rest_is_field_included( '_links', $fields ) || rest_is_field_included( '_embedded', $fields ) ) { 357 $response->add_links( $this->prepare_links( $theme ) ); 358 } 359 360 /** 361 * Filters theme data returned from the REST API. 362 * 363 * @since 5.0.0 364 * 365 * @param WP_REST_Response $response The response object. 366 * @param WP_Theme $theme Theme object used to create response. 367 * @param WP_REST_Request $request Request object. 368 */ 369 return apply_filters( 'rest_prepare_theme', $response, $theme, $request ); 370 } 371 372 /** 373 * Prepares links for the request. 374 * 375 * @since 5.7.0 376 * 377 * @param WP_Theme $theme Theme data. 378 * @return array Links for the given block type. 379 */ 380 protected function prepare_links( $theme ) { 381 $links = array( 382 'self' => array( 383 'href' => rest_url( sprintf( '%s/%s/%s', $this->namespace, $this->rest_base, $theme->get_stylesheet() ) ), 384 ), 385 'collection' => array( 386 'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ), 387 ), 388 ); 389 390 if ( $this->is_same_theme( $theme, wp_get_theme() ) ) { 391 // This creates a record for the active theme if not existent. 392 $id = WP_Theme_JSON_Resolver::get_user_global_styles_post_id(); 393 } else { 394 $user_cpt = WP_Theme_JSON_Resolver::get_user_data_from_wp_global_styles( $theme ); 395 $id = isset( $user_cpt['ID'] ) ? $user_cpt['ID'] : null; 396 } 397 398 if ( $id ) { 399 $links['https://api.w.org/user-global-styles'] = array( 400 'href' => rest_url( 'wp/v2/global-styles/' . $id ), 401 ); 402 } 403 404 return $links; 405 } 406 407 /** 408 * Helper function to compare two themes. 409 * 410 * @since 5.7.0 411 * 412 * @param WP_Theme $theme_a First theme to compare. 413 * @param WP_Theme $theme_b Second theme to compare. 414 * @return bool 415 */ 416 protected function is_same_theme( $theme_a, $theme_b ) { 417 return $theme_a->get_stylesheet() === $theme_b->get_stylesheet(); 418 } 419 420 /** 421 * Prepares the theme support value for inclusion in the REST API response. 422 * 423 * @since 5.5.0 424 * 425 * @param mixed $support The raw value from get_theme_support(). 426 * @param array $args The feature's registration args. 427 * @param string $feature The feature name. 428 * @param WP_REST_Request $request The request object. 429 * @return mixed The prepared support value. 430 */ 431 protected function prepare_theme_support( $support, $args, $feature, $request ) { 432 $schema = $args['show_in_rest']['schema']; 433 434 if ( 'boolean' === $schema['type'] ) { 435 return true; 436 } 437 438 if ( is_array( $support ) && ! $args['variadic'] ) { 439 $support = $support[0]; 440 } 441 442 return rest_sanitize_value_from_schema( $support, $schema ); 443 } 444 445 /** 446 * Retrieves the theme's schema, conforming to JSON Schema. 447 * 448 * @since 5.0.0 449 * 450 * @return array Item schema data. 451 */ 452 public function get_item_schema() { 453 if ( $this->schema ) { 454 return $this->add_additional_fields_schema( $this->schema ); 455 } 456 457 $schema = array( 458 '$schema' => 'http://json-schema.org/draft-04/schema#', 459 'title' => 'theme', 460 'type' => 'object', 461 'properties' => array( 462 'stylesheet' => array( 463 'description' => __( 'The theme\'s stylesheet. This uniquely identifies the theme.' ), 464 'type' => 'string', 465 'readonly' => true, 466 ), 467 'stylesheet_uri' => array( 468 'description' => __( 'The uri for the theme\'s stylesheet directory.' ), 469 'type' => 'string', 470 'format' => 'uri', 471 'readonly' => true, 472 ), 473 'template' => array( 474 '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.' ), 475 'type' => 'string', 476 'readonly' => true, 477 ), 478 'template_uri' => array( 479 '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.' ), 480 'type' => 'string', 481 'format' => 'uri', 482 'readonly' => true, 483 ), 484 'author' => array( 485 'description' => __( 'The theme author.' ), 486 'type' => 'object', 487 'readonly' => true, 488 'properties' => array( 489 'raw' => array( 490 'description' => __( 'The theme author\'s name, as found in the theme header.' ), 491 'type' => 'string', 492 ), 493 'rendered' => array( 494 'description' => __( 'HTML for the theme author, transformed for display.' ), 495 'type' => 'string', 496 ), 497 ), 498 ), 499 'author_uri' => array( 500 'description' => __( 'The website of the theme author.' ), 501 'type' => 'object', 502 'readonly' => true, 503 'properties' => array( 504 'raw' => array( 505 'description' => __( 'The website of the theme author, as found in the theme header.' ), 506 'type' => 'string', 507 'format' => 'uri', 508 ), 509 'rendered' => array( 510 'description' => __( 'The website of the theme author, transformed for display.' ), 511 'type' => 'string', 512 'format' => 'uri', 513 ), 514 ), 515 ), 516 'description' => array( 517 'description' => __( 'A description of the theme.' ), 518 'type' => 'object', 519 'readonly' => true, 520 'properties' => array( 521 'raw' => array( 522 'description' => __( 'The theme description, as found in the theme header.' ), 523 'type' => 'string', 524 ), 525 'rendered' => array( 526 'description' => __( 'The theme description, transformed for display.' ), 527 'type' => 'string', 528 ), 529 ), 530 ), 531 'is_block_theme' => array( 532 'description' => __( 'Whether the theme is a block-based theme.' ), 533 'type' => 'boolean', 534 'readonly' => true, 535 ), 536 'name' => array( 537 'description' => __( 'The name of the theme.' ), 538 'type' => 'object', 539 'readonly' => true, 540 'properties' => array( 541 'raw' => array( 542 'description' => __( 'The theme name, as found in the theme header.' ), 543 'type' => 'string', 544 ), 545 'rendered' => array( 546 'description' => __( 'The theme name, transformed for display.' ), 547 'type' => 'string', 548 ), 549 ), 550 ), 551 'requires_php' => array( 552 'description' => __( 'The minimum PHP version required for the theme to work.' ), 553 'type' => 'string', 554 'readonly' => true, 555 ), 556 'requires_wp' => array( 557 'description' => __( 'The minimum WordPress version required for the theme to work.' ), 558 'type' => 'string', 559 'readonly' => true, 560 ), 561 'screenshot' => array( 562 'description' => __( 'The theme\'s screenshot URL.' ), 563 'type' => 'string', 564 'format' => 'uri', 565 'readonly' => true, 566 ), 567 'tags' => array( 568 'description' => __( 'Tags indicating styles and features of the theme.' ), 569 'type' => 'object', 570 'readonly' => true, 571 'properties' => array( 572 'raw' => array( 573 'description' => __( 'The theme tags, as found in the theme header.' ), 574 'type' => 'array', 575 'items' => array( 576 'type' => 'string', 577 ), 578 ), 579 'rendered' => array( 580 'description' => __( 'The theme tags, transformed for display.' ), 581 'type' => 'string', 582 ), 583 ), 584 ), 585 'textdomain' => array( 586 'description' => __( 'The theme\'s text domain.' ), 587 'type' => 'string', 588 'readonly' => true, 589 ), 590 'theme_supports' => array( 591 'description' => __( 'Features supported by this theme.' ), 592 'type' => 'object', 593 'readonly' => true, 594 'properties' => array(), 595 ), 596 'theme_uri' => array( 597 'description' => __( 'The URI of the theme\'s webpage.' ), 598 'type' => 'object', 599 'readonly' => true, 600 'properties' => array( 601 'raw' => array( 602 'description' => __( 'The URI of the theme\'s webpage, as found in the theme header.' ), 603 'type' => 'string', 604 'format' => 'uri', 605 ), 606 'rendered' => array( 607 'description' => __( 'The URI of the theme\'s webpage, transformed for display.' ), 608 'type' => 'string', 609 'format' => 'uri', 610 ), 611 ), 612 ), 613 'version' => array( 614 'description' => __( 'The theme\'s current version.' ), 615 'type' => 'string', 616 'readonly' => true, 617 ), 618 'status' => array( 619 'description' => __( 'A named status for the theme.' ), 620 'type' => 'string', 621 'enum' => array( 'inactive', 'active' ), 622 ), 623 ), 624 ); 625 626 foreach ( get_registered_theme_features() as $feature => $config ) { 627 if ( ! is_array( $config['show_in_rest'] ) ) { 628 continue; 629 } 630 631 $name = $config['show_in_rest']['name']; 632 633 $schema['properties']['theme_supports']['properties'][ $name ] = $config['show_in_rest']['schema']; 634 } 635 636 $this->schema = $schema; 637 638 return $this->add_additional_fields_schema( $this->schema ); 639 } 640 641 /** 642 * Retrieves the search params for the themes collection. 643 * 644 * @since 5.0.0 645 * 646 * @return array Collection parameters. 647 */ 648 public function get_collection_params() { 649 $query_params = array( 650 'status' => array( 651 'description' => __( 'Limit result set to themes assigned one or more statuses.' ), 652 'type' => 'array', 653 'items' => array( 654 'enum' => array( 'active', 'inactive' ), 655 'type' => 'string', 656 ), 657 ), 658 ); 659 660 /** 661 * Filters REST API collection parameters for the themes controller. 662 * 663 * @since 5.0.0 664 * 665 * @param array $query_params JSON Schema-formatted collection parameters. 666 */ 667 return apply_filters( 'rest_themes_collection_params', $query_params ); 668 } 669 670 /** 671 * Sanitizes and validates the list of theme status. 672 * 673 * @since 5.0.0 674 * @deprecated 5.7.0 675 * 676 * @param string|array $statuses One or more theme statuses. 677 * @param WP_REST_Request $request Full details about the request. 678 * @param string $parameter Additional parameter to pass to validation. 679 * @return array|WP_Error A list of valid statuses, otherwise WP_Error object. 680 */ 681 public function sanitize_theme_status( $statuses, $request, $parameter ) { 682 _deprecated_function( __METHOD__, '5.7.0' ); 683 684 $statuses = wp_parse_slug_list( $statuses ); 685 686 foreach ( $statuses as $status ) { 687 $result = rest_validate_request_arg( $status, $request, $parameter ); 688 689 if ( is_wp_error( $result ) ) { 690 return $result; 691 } 692 } 693 694 return $statuses; 695 } 696 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Thu Nov 21 08:20:01 2024 | Cross-referenced by PHPXref |