Ticket #45016: 45016.diff

src/wp-includes/rest-api/endpoints/class-wp-rest-themes-controller.php

@@ +1 @@
+<?php
+/**
+ * REST API: WP_REST_Themes_Controller class
+ *
+ * @package WordPress
+ * @subpackage REST_API
+ * @since 5.0.0
+ */
+
+/**
+ * Core class used to manage themes via the REST API.
+ *
+ * @since 5.0.0
+ *
+ * @see WP_REST_Controller
+ */
+class WP_REST_Themes_Controller extends WP_REST_Controller {
+
+        /**
+         * Constructor.
+         *
+         * @since 5.0.0
+         */
+        public function __construct() {
+                $this->namespace = 'wp/v2';
+                $this->rest_base = 'themes';
+        }
+
+        /**
+         * Registers the routes for the objects of the controller.
+         *
+         * @since 5.0.0
+         *
+         * @see register_rest_route()
+         */
+        public function register_routes() {
+                register_rest_route(
+                        $this->namespace,
+                        '/' . $this->rest_base,
+                        array(
+                                array(
+                                        'methods'             => WP_REST_Server::READABLE,
+                                        'callback'            => array( $this, 'get_items' ),
+                                        'permission_callback' => array( $this, 'get_items_permissions_check' ),
+                                        'args'                => $this->get_collection_params(),
+                                ),
+                                'schema' => array( $this, 'get_item_schema' ),
+                        )
+                );
+        }
+
+        /**
+         * Checks if a given request has access to read the theme.
+         *
+         * @since 5.0.0
+         *
+         * @param WP_REST_Request $request Full details about the request.
+         * @return true|WP_Error True if the request has read access for the item, otherwise WP_Error object.
+         */
+        public function get_items_permissions_check( $request ) {
+                if ( ! is_user_logged_in() || ! current_user_can( 'edit_posts' ) ) {
+                        return new WP_Error( 'rest_user_cannot_view', __( 'Sorry, you are not allowed to view themes.', 'gutenberg' ), array( 'status' => rest_authorization_required_code() ) );
+                }
+
+                return true;
+        }
+
+        /**
+         * Retrieves a collection of themes.
+         *
+         * @since 5.0.0
+         *
+         * @param WP_REST_Request $request Full details about the request.
+         * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
+         */
+        public function get_items( $request ) {
+                // Retrieve the list of registered collection query parameters.
+                $registered = $this->get_collection_params();
+                $themes     = array();
+
+                if ( isset( $registered['status'], $request['status'] ) && in_array( 'active', $request['status'], true ) ) {
+                        $active_theme = wp_get_theme();
+                        $active_theme = $this->prepare_item_for_response( $active_theme, $request );
+                        $themes[]     = $this->prepare_response_for_collection( $active_theme );
+                }
+
+                $response = rest_ensure_response( $themes );
+
+                $response->header( 'X-WP-Total', count( $themes ) );
+                $response->header( 'X-WP-TotalPages', count( $themes ) );
+
+                return $response;
+        }
+
+        /**
+         * Prepares a single theme output for response.
+         *
+         * @since 5.0.0
+         *
+         * @param WP_Theme        $theme   Theme object.
+         * @param WP_REST_Request $request Request object.
+         * @return WP_REST_Response Response object.
+         */
+        public function prepare_item_for_response( $theme, $request ) {
+                $data   = array();
+                $fields = $this->get_fields_for_response( $request );
+
+                if ( in_array( 'theme_supports', $fields, true ) ) {
+                        $formats                           = get_theme_support( 'post-formats' );
+                        $formats                           = is_array( $formats ) ? array_values( $formats[0] ) : array();
+                        $formats                           = array_merge( array( 'standard' ), $formats );
+                        $data['theme_supports']['formats'] = $formats;
+
+                        $data['theme_supports']['post-thumbnails'] = false;
+                        $post_thumbnails                           = get_theme_support( 'post-thumbnails' );
+
+                        if ( $post_thumbnails ) {
+                                // $post_thumbnails can contain a nested array of post types.
+                                // e.g. array( array( 'post', 'page' ) ).
+                                $data['theme_supports']['post-thumbnails'] = is_array( $post_thumbnails ) ? $post_thumbnails[0] : true;
+                        }
+                }
+
+                $data = $this->add_additional_fields_to_object( $data, $request );
+
+                // Wrap the data in a response object.
+                $response = rest_ensure_response( $data );
+
+                /**
+                 * Filters theme data returned from the REST API.
+                 *
+                 * @since 5.0.0
+                 *
+                 * @param WP_REST_Response $response The response object.
+                 * @param WP_Theme         $theme    Theme object used to create response.
+                 * @param WP_REST_Request  $request  Request object.
+                 */
+                return apply_filters( 'rest_prepare_theme', $response, $theme, $request );
+        }
+
+        /**
+         * Retrieves the theme's schema, conforming to JSON Schema.
+         *
+         * @since 5.0.0
+         *
+         * @return array Item schema data.
+         */
+        public function get_item_schema() {
+                $schema = array(
+                        '$schema'    => 'http://json-schema.org/draft-04/schema#',
+                        'title'      => 'theme',
+                        'type'       => 'object',
+                        'properties' => array(
+                                'theme_supports' => array(
+                                        'description' => __( 'Features supported by this theme.', 'gutenberg' ),
+                                        'type'        => 'array',
+                                        'readonly'    => true,
+                                        'properties'  => array(
+                                                'formats'         => array(
+                                                        'description' => __( 'Post formats supported.', 'gutenberg' ),
+                                                        'type'        => 'array',
+                                                        'readonly'    => true,
+                                                ),
+                                                'post-thumbnails' => array(
+                                                        'description' => __( 'Whether the theme supports post thumbnails.', 'gutenberg' ),
+                                                        'type'        => array( 'array', 'bool' ),
+                                                        'readonly'    => true,
+                                                ),
+                                        ),
+                                ),
+                        ),
+                );
+
+                return $this->add_additional_fields_schema( $schema );
+        }
+
+        /**
+         * Retrieves the search params for the themes collection.
+         *
+         * @since 5.0.0
+         *
+         * @return array Collection parameters.
+         */
+        public function get_collection_params() {
+                $query_params = parent::get_collection_params();
+
+                $query_params['status'] = array(
+                        'description'       => __( 'Limit result set to themes assigned one or more statuses.', 'gutenberg' ),
+                        'type'              => 'array',
+                        'items'             => array(
+                                'enum' => array( 'active' ),
+                                'type' => 'string',
+                        ),
+                        'required'          => true,
+                        'sanitize_callback' => array( $this, 'sanitize_theme_status' ),
+                );
+
+                /**
+                 * Filter collection parameters for the themes controller.
+                 *
+                 * @since 5.0.0
+                 *
+                 * @param array        $query_params JSON Schema-formatted collection parameters.
+                 */
+                return apply_filters( 'rest_themes_collection_params', $query_params );
+        }
+
+        /**
+         * Sanitizes and validates the list of theme status.
+         *
+         * @since 5.0.0
+         *
+         * @param  string|array    $statuses  One or more theme statuses.
+         * @param  WP_REST_Request $request   Full details about the request.
+         * @param  string          $parameter Additional parameter to pass to validation.
+         * @return array|WP_Error A list of valid statuses, otherwise WP_Error object.
+         */
+        public function sanitize_theme_status( $statuses, $request, $parameter ) {
+                $statuses = wp_parse_slug_list( $statuses );
+
+                foreach ( $statuses as $status ) {
+                        $result = rest_validate_request_arg( $status, $request, $parameter );
+
+                        if ( is_wp_error( $result ) ) {
+                                return $result;
+                        }
+                }
+
+                return $statuses;
+        }
+}

src/wp-includes/rest-api.php

@@ -233 +233 @@
         // Settings.
         $controller = new WP_REST_Settings_Controller;
         $controller->register_routes();
+
+        // Themes.
+        $controller = new WP_REST_Themes_Controller;
+        $controller->register_routes();
 }
 
 /**

src/wp-settings.php

@@ -234 +234 @@
 require( ABSPATH . WPINC . '/rest-api/endpoints/class-wp-rest-users-controller.php' );
 require( ABSPATH . WPINC . '/rest-api/endpoints/class-wp-rest-comments-controller.php' );
 require( ABSPATH . WPINC . '/rest-api/endpoints/class-wp-rest-settings-controller.php' );
+require( ABSPATH . WPINC . '/rest-api/endpoints/class-wp-rest-themes-controller.php' );
 require( ABSPATH . WPINC . '/rest-api/fields/class-wp-rest-meta-fields.php' );
 require( ABSPATH . WPINC . '/rest-api/fields/class-wp-rest-comment-meta-fields.php' );
 require( ABSPATH . WPINC . '/rest-api/fields/class-wp-rest-post-meta-fields.php' );

tests/phpunit/tests/rest-api/rest-schema-setup.php

@@ -111 +111 @@
                         '/wp/v2/comments',
                         '/wp/v2/comments/(?P<id>[\\d]+)',
                         '/wp/v2/settings',
+                        '/wp/v2/themes',
                 );
 
                 $this->assertEquals( $expected_routes, $routes );

tests/phpunit/tests/rest-api/rest-themes-controller.php

@@ +1 @@
+<?php
+/**
+ * Unit tests covering WP_REST_Themes_Controller functionality.
+ *
+ * @package WordPress
+ * @subpackage REST API
+ */
+
+/**
+ * @group restapi-themes
+ * @group restapi
+ */
+class WP_Test_REST_Themes_Controller extends WP_Test_REST_Controller_Testcase {
+        /**
+         * Subscriber user ID.
+         *
+         * @since 5.0.0
+         *
+         * @var int $subscriber_id
+         */
+        protected static $subscriber_id;
+
+        /**
+         * Contributor user ID.
+         *
+         * @since 5.0.0
+         *
+         * @var int $contributor_id
+         */
+        protected static $contributor_id;
+
+        /**
+         * The current theme object.
+         *
+         * @since 5.0.0
+         *
+         * @var WP_Theme $current_theme
+         */
+        protected static $current_theme;
+
+        /**
+         * The REST API route for the active theme.
+         *
+         * @since 5.0.0
+         *
+         * @var string $themes_route
+         */
+        protected static $themes_route = '/wp/v2/themes';
+
+        /**
+         * Performs a REST API request for the active theme.
+         *
+         * @since 5.0.0
+         *
+         * @param string $method Optional. Request method. Default GET.
+         * @return WP_REST_Response The request's response.
+         */
+        protected function perform_active_theme_request( $method = 'GET' ) {
+                $request = new WP_REST_Request( $method, self::$themes_route );
+                $request->set_param( 'status', 'active' );
+
+                return rest_get_server()->dispatch( $request );
+        }
+
+        /**
+         * Check that common properties are included in a response.
+         *
+         * @since 5.0.0
+         *
+         * @param WP_REST_Response $response Current REST API response.
+         */
+        protected function check_get_theme_response( $response ) {
+                if ( $response instanceof WP_REST_Response ) {
+                        $headers  = $response->get_headers();
+                        $response = $response->get_data();
+                } else {
+                        $headers = array();
+                }
+
+                $this->assertArrayHasKey( 'X-WP-Total', $headers );
+                $this->assertEquals( 1, $headers['X-WP-Total'] );
+                $this->assertArrayHasKey( 'X-WP-TotalPages', $headers );
+                $this->assertEquals( 1, $headers['X-WP-TotalPages'] );
+        }
+
+        /**
+         * Set up class test fixtures.
+         *
+         * @since 5.0.0
+         *
+         * @param WP_UnitTest_Factory $factory WordPress unit test factory.
+         */
+        public static function wpSetUpBeforeClass( $factory ) {
+                self::$subscriber_id  = $factory->user->create(
+                        array(
+                                'role' => 'subscriber',
+                        )
+                );
+                self::$contributor_id = $factory->user->create(
+                        array(
+                                'role' => 'contributor',
+                        )
+                );
+                self::$current_theme  = wp_get_theme();
+
+                wp_set_current_user( self::$contributor_id );
+        }
+
+        /**
+         * Clean up test fixtures.
+         *
+         * @since 5.0.0
+         */
+        public static function wpTearDownAfterClass() {
+                self::delete_user( self::$subscriber_id );
+                self::delete_user( self::$contributor_id );
+        }
+
+        /**
+         * Set up each test method.
+         *
+         * @since 5.0.0
+         */
+        public function setUp() {
+                parent::setUp();
+
+                wp_set_current_user( self::$contributor_id );
+        }
+
+        /**
+         * Theme routes should be registered correctly.
+         *
+         * @ticket 45016
+         */
+        public function test_register_routes() {
+                $routes = rest_get_server()->get_routes();
+                $this->assertArrayHasKey( self::$themes_route, $routes );
+        }
+
+        /**
+         * Test retrieving a collection of themes.
+         *
+         * @ticket 45016
+         */
+        public function test_get_items() {
+                $response = self::perform_active_theme_request();
+
+                $this->assertEquals( 200, $response->get_status() );
+                $data = $response->get_data();
+
+                $this->check_get_theme_response( $response );
+                $fields = array(
+                        'theme_supports',
+                );
+                $this->assertEqualSets( $fields, array_keys( $data[0] ) );
+        }
+
+        /**
+         * An error should be returned when the user does not have the edit_posts capability.
+         *
+         * @ticket 45016
+         */
+        public function test_get_items_no_permission() {
+                wp_set_current_user( self::$subscriber_id );
+                $response = self::perform_active_theme_request();
+                $this->assertErrorResponse( 'rest_user_cannot_view', $response, 403 );
+        }
+
+        /**
+         * Test an item is prepared for the response.
+         *
+         * @ticket 45016
+         */
+        public function test_prepare_item() {
+                $response = self::perform_active_theme_request();
+                $this->assertEquals( 200, $response->get_status() );
+                $this->check_get_theme_response( $response );
+        }
+
+        /**
+         * Verify the theme schema.
+         *
+         * @ticket 45016
+         */
+        public function test_get_item_schema() {
+                $response   = self::perform_active_theme_request( 'OPTIONS' );
+                $data       = $response->get_data();
+                $properties = $data['schema']['properties'];
+                $this->assertEquals( 1, count( $properties ) );
+                $this->assertArrayHasKey( 'theme_supports', $properties );
+
+                $this->assertEquals( 2, count( $properties['theme_supports']['properties'] ) );
+                $this->assertArrayHasKey( 'formats', $properties['theme_supports']['properties'] );
+                $this->assertArrayHasKey( 'post-thumbnails', $properties['theme_supports']['properties'] );
+        }
+
+        /**
+         * Should include relevant data in the 'theme_supports' key.
+         *
+         * @ticket 45016
+         */
+        public function test_theme_supports_formats() {
+                remove_theme_support( 'post-formats' );
+                $response = self::perform_active_theme_request();
+                $result   = $response->get_data();
+                $this->assertTrue( isset( $result[0]['theme_supports'] ) );
+                $this->assertTrue( isset( $result[0]['theme_supports']['formats'] ) );
+                $this->assertSame( array( 'standard' ), $result[0]['theme_supports']['formats'] );
+        }
+
+        /**
+         * Test when a theme only supports some post formats.
+         *
+         * @ticket 45016
+         */
+        public function test_theme_supports_formats_non_default() {
+                add_theme_support( 'post-formats', array( 'aside', 'video' ) );
+                $response = self::perform_active_theme_request();
+                $result   = $response->get_data();
+                $this->assertTrue( isset( $result[0]['theme_supports'] ) );
+                $this->assertTrue( isset( $result[0]['theme_supports']['formats'] ) );
+                $this->assertSame( array( 'standard', 'aside', 'video' ), $result[0]['theme_supports']['formats'] );
+        }
+
+        /**
+         * Test when a theme does not support post thumbnails.
+         *
+         * @ticket 45016
+         */
+        public function test_theme_supports_post_thumbnails_false() {
+                remove_theme_support( 'post-thumbnails' );
+                $response = self::perform_active_theme_request();
+
+                $result = $response->get_data();
+                $this->assertTrue( isset( $result[0]['theme_supports'] ) );
+                $this->assertTrue( isset( $result[0]['theme_supports']['post-thumbnails'] ) );
+                $this->assertFalse( $result[0]['theme_supports']['post-thumbnails'] );
+        }
+
+        /**
+         * Test when a theme supports all post thumbnails.
+         *
+         * @ticket 45016
+         */
+        public function test_theme_supports_post_thumbnails_true() {
+                remove_theme_support( 'post-thumbnails' );
+                add_theme_support( 'post-thumbnails' );
+                $response = self::perform_active_theme_request();
+                $result   = $response->get_data();
+                $this->assertTrue( isset( $result[0]['theme_supports'] ) );
+                $this->assertTrue( $result[0]['theme_supports']['post-thumbnails'] );
+        }
+
+        /**
+         * Test when a theme only supports post thumbnails for certain post types.
+         *
+         * @ticket 45016
+         */
+        public function test_theme_supports_post_thumbnails_array() {
+                remove_theme_support( 'post-thumbnails' );
+                add_theme_support( 'post-thumbnails', array( 'post' ) );
+                $response = self::perform_active_theme_request();
+                $result   = $response->get_data();
+                $this->assertTrue( isset( $result[0]['theme_supports'] ) );
+                $this->assertEquals( array( 'post' ), $result[0]['theme_supports']['post-thumbnails'] );
+        }
+
+        /**
+         * It should be possible to register custom fields to the endpoint.
+         *
+         * @ticket 45016
+         */
+        public function test_get_additional_field_registration() {
+                $schema = array(
+                        'type'        => 'integer',
+                        'description' => 'Some integer of mine',
+                        'enum'        => array( 1, 2, 3, 4 ),
+                );
+
+                register_rest_field(
+                        'theme',
+                        'my_custom_int',
+                        array(
+                                'schema'       => $schema,
+                                'get_callback' => array( $this, 'additional_field_get_callback' ),
+                        )
+                );
+
+                $response = self::perform_active_theme_request( 'OPTIONS' );
+                $data     = $response->get_data();
+
+                $this->assertArrayHasKey( 'my_custom_int', $data['schema']['properties'] );
+                $this->assertEquals( $schema, $data['schema']['properties']['my_custom_int'] );
+
+                $response = self::perform_active_theme_request( 'GET' );
+                $data     = $response->get_data();
+                $this->assertArrayHasKey( 'my_custom_int', $data[0] );
+                $this->assertSame( 2, $data[0]['my_custom_int'] );
+
+                global $wp_rest_additional_fields;
+                $wp_rest_additional_fields = array();
+        }
+
+        /**
+         * Return a value for the custom field.
+         *
+         * @since 5.0.0
+         *
+         * @param array $theme Theme data array.
+         * @return int Additional field value.
+         */
+        public function additional_field_get_callback( $theme ) {
+                return 2;
+        }
+
+        /**
+         * The create_item() method does not exist for themes.
+         */
+        public function test_create_item() {}
+
+        /**
+         * The update_item() method does not exist for themes.
+         */
+        public function test_update_item() {}
+
+        /**
+         * The get_item() method does not exist for themes.
+         */
+        public function test_get_item() {}
+
+        /**
+         * The delete_item() method does not exist for themes.
+         */
+        public function test_delete_item() {}
+
+        /**
+         * Context is not supported for themes.
+         */
+        public function test_context_param() {}
+}

tests/qunit/fixtures/wp-api-generated.js

@@ -3517 +3517 @@
             "_links": {
                 "self": "http://example.org/index.php?rest_route=/wp/v2/settings"
             }
+        },
+        "/wp/v2/themes": {
+            "namespace": "wp/v2",
+            "methods": [
+                "GET"
+            ],
+            "endpoints": [
+                {
+                    "methods": [
+                        "GET"
+                    ],
+                    "args": {
+                        "context": {
+                            "required": false,
+                            "description": "Scope under which the request is made; determines fields present in response.",
+                            "type": "string"
+                        },
+                        "page": {
+                            "required": false,
+                            "default": 1,
+                            "description": "Current page of the collection.",
+                            "type": "integer"
+                        },
+                        "per_page": {
+                            "required": false,
+                            "default": 10,
+                            "description": "Maximum number of items to be returned in result set.",
+                            "type": "integer"
+                        },
+                        "search": {
+                            "required": false,
+                            "description": "Limit results to those matching a string.",
+                            "type": "string"
+                        },
+                        "status": {
+                            "required": true,
+                            "description": "Limit result set to themes assigned one or more statuses.",
+                            "type": "array",
+                            "items": {
+                                "enum": [
+                                    "active"
+                                ],
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            ],
+            "_links": {
+                "self": "http://example.org/index.php?rest_route=/wp/v2/themes"
+            }
         }
     }
 };