[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * REST API: WP_REST_Icons_Controller class
   4   *
   5   * @package    WordPress
   6   * @subpackage REST_API
   7   * @since      7.0.0
   8   */
   9  
  10  /**
  11   * Controller which provides a REST endpoint for the editor to read registered
  12   * icons. For the time being, only core icons are available, which are defined
  13   * in a single manifest file (wp-includes/assets/icon-library-manifest.php).
  14   * Icons are comprised of their SVG source, a name and a translatable label.
  15   *
  16   * @since 7.0.0
  17   *
  18   * @see WP_REST_Controller
  19   */
  20  class WP_REST_Icons_Controller extends WP_REST_Controller {
  21  
  22      /**
  23       * Constructs the controller.
  24       *
  25       * @since 7.0.0
  26       */
  27  	public function __construct() {
  28          $this->namespace = 'wp/v2';
  29          $this->rest_base = 'icons';
  30      }
  31  
  32      /**
  33       * Registers the routes for the objects of the controller.
  34       *
  35       * @since 7.0.0
  36       */
  37  	public function register_routes() {
  38          register_rest_route(
  39              $this->namespace,
  40              '/' . $this->rest_base,
  41              array(
  42                  array(
  43                      'methods'             => WP_REST_Server::READABLE,
  44                      'callback'            => array( $this, 'get_items' ),
  45                      'permission_callback' => array( $this, 'get_items_permissions_check' ),
  46                      'args'                => $this->get_collection_params(),
  47                  ),
  48                  'schema' => array( $this, 'get_public_item_schema' ),
  49              )
  50          );
  51  
  52          register_rest_route(
  53              $this->namespace,
  54              '/' . $this->rest_base . '/(?P<name>[a-z][a-z0-9-]*/[a-z][a-z0-9-]*)',
  55              array(
  56                  'args'   => array(
  57                      'name' => array(
  58                          'description' => __( 'Icon name.' ),
  59                          'type'        => 'string',
  60                      ),
  61                  ),
  62                  array(
  63                      'methods'             => WP_REST_Server::READABLE,
  64                      'callback'            => array( $this, 'get_item' ),
  65                      'permission_callback' => array( $this, 'get_item_permissions_check' ),
  66                      'args'                => array(
  67                          'context' => $this->get_context_param( array( 'default' => 'view' ) ),
  68                      ),
  69                  ),
  70                  'schema' => array( $this, 'get_public_item_schema' ),
  71              )
  72          );
  73      }
  74  
  75      /**
  76       * Checks whether a given request has permission to read icons.
  77       *
  78       * @since 7.0.0
  79       *
  80       * @param WP_REST_Request $request Full details about the request.
  81       * @return true|WP_Error True if the request has read access, WP_Error object otherwise.
  82       */
  83  	public function get_items_permissions_check(
  84          // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
  85          $request
  86      ) {
  87          if ( current_user_can( 'edit_posts' ) ) {
  88              return true;
  89          }
  90  
  91          foreach ( get_post_types( array( 'show_in_rest' => true ), 'objects' ) as $post_type ) {
  92              if ( current_user_can( $post_type->cap->edit_posts ) ) {
  93                  return true;
  94              }
  95          }
  96  
  97          return new WP_Error(
  98              'rest_cannot_view',
  99              __( 'Sorry, you are not allowed to view the registered icons.' ),
 100              array( 'status' => rest_authorization_required_code() )
 101          );
 102      }
 103  
 104      /**
 105       * Checks if a given request has access to read a specific icon.
 106       *
 107       * @since 7.0.0
 108       *
 109       * @param WP_REST_Request $request Full details about the request.
 110       * @return true|WP_Error True if the request has read access for the item, WP_Error object otherwise.
 111       */
 112  	public function get_item_permissions_check( $request ) {
 113          $check = $this->get_items_permissions_check( $request );
 114          if ( is_wp_error( $check ) ) {
 115              return $check;
 116          }
 117  
 118          return true;
 119      }
 120  
 121      /**
 122       * Retrieves all icons.
 123       *
 124       * @since 7.0.0
 125       *
 126       * @param WP_REST_Request $request Full details about the request.
 127       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 128       */
 129  	public function get_items( $request ) {
 130          $response = array();
 131          $search   = $request->get_param( 'search' );
 132          $icons    = WP_Icons_Registry::get_instance()->get_registered_icons( $search );
 133          foreach ( $icons as $icon ) {
 134              $prepared_icon = $this->prepare_item_for_response( $icon, $request );
 135              $response[]    = $this->prepare_response_for_collection( $prepared_icon );
 136          }
 137          return rest_ensure_response( $response );
 138      }
 139  
 140      /**
 141       * Retrieves a specific icon.
 142       *
 143       * @since 7.0.0
 144       *
 145       * @param WP_REST_Request $request Full details about the request.
 146       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 147       */
 148  	public function get_item( $request ) {
 149          $icon = $this->get_icon( $request['name'] );
 150          if ( is_wp_error( $icon ) ) {
 151              return $icon;
 152          }
 153  
 154          $data = $this->prepare_item_for_response( $icon, $request );
 155          return rest_ensure_response( $data );
 156      }
 157  
 158      /**
 159       * Retrieves a specific icon from the registry.
 160       *
 161       * @since 7.0.0
 162       *
 163       * @param string $name Icon name.
 164       * @return array|WP_Error Icon data on success, or WP_Error object on failure.
 165       */
 166  	public function get_icon( $name ) {
 167          $registry = WP_Icons_Registry::get_instance();
 168          $icon     = $registry->get_registered_icon( $name );
 169  
 170          if ( null === $icon ) {
 171              return new WP_Error(
 172                  'rest_icon_not_found',
 173                  sprintf(
 174                      // translators: %s is the name of any user-provided name
 175                      __( 'Icon not found: "%s".' ),
 176                      $name
 177                  ),
 178                  array( 'status' => 404 )
 179              );
 180          }
 181  
 182          return $icon;
 183      }
 184  
 185      /**
 186       * Prepare a raw icon before it gets output in a REST API response.
 187       *
 188       * @since 7.0.0
 189       *
 190       * @param array           $item    Raw icon as registered, before any changes.
 191       * @param WP_REST_Request $request Request object.
 192       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 193       */
 194  	public function prepare_item_for_response( $item, $request ) {
 195          $fields = $this->get_fields_for_response( $request );
 196          $keys   = array(
 197              'name'    => 'name',
 198              'label'   => 'label',
 199              'content' => 'content',
 200          );
 201          $data   = array();
 202          foreach ( $keys as $item_key => $rest_key ) {
 203              if ( isset( $item[ $item_key ] ) && rest_is_field_included( $rest_key, $fields ) ) {
 204                  $data[ $rest_key ] = $item[ $item_key ];
 205              }
 206          }
 207  
 208          $context = ! empty( $request['context'] ) ? $request['context'] : 'view';
 209          $data    = $this->add_additional_fields_to_object( $data, $request );
 210          $data    = $this->filter_response_by_context( $data, $context );
 211          return rest_ensure_response( $data );
 212      }
 213  
 214      /**
 215       * Retrieves the icon schema, conforming to JSON Schema.
 216       *
 217       * @since 7.0.0
 218       *
 219       * @return array Item schema data.
 220       */
 221  	public function get_item_schema() {
 222          if ( $this->schema ) {
 223              return $this->add_additional_fields_schema( $this->schema );
 224          }
 225  
 226          $schema = array(
 227              '$schema'    => 'http://json-schema.org/draft-04/schema#',
 228              'title'      => 'icon',
 229              'type'       => 'object',
 230              'properties' => array(
 231                  'name'    => array(
 232                      'description' => __( 'The icon name.' ),
 233                      'type'        => 'string',
 234                      'readonly'    => true,
 235                      'context'     => array( 'view', 'edit', 'embed' ),
 236                  ),
 237                  'label'   => array(
 238                      'description' => __( 'The icon label.' ),
 239                      'type'        => 'string',
 240                      'readonly'    => true,
 241                      'context'     => array( 'view', 'edit', 'embed' ),
 242                  ),
 243                  'content' => array(
 244                      'description' => __( 'The icon content (SVG markup).' ),
 245                      'type'        => 'string',
 246                      'readonly'    => true,
 247                      'context'     => array( 'view', 'edit', 'embed' ),
 248                  ),
 249              ),
 250          );
 251  
 252          $this->schema = $schema;
 253  
 254          return $this->add_additional_fields_schema( $this->schema );
 255      }
 256  
 257      /**
 258       * Retrieves the query params for the icons collection.
 259       *
 260       * @since 7.0.0
 261       *
 262       * @return array Collection parameters.
 263       */
 264  	public function get_collection_params() {
 265          $query_params                       = parent::get_collection_params();
 266          $query_params['context']['default'] = 'view';
 267          return $query_params;
 268      }
 269  }