[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * REST API: WP_REST_Icons_Controller class
   5   *
   6   * @package    WordPress
   7   * @subpackage REST_API
   8   * @since      7.0.0
   9   */
  10  
  11  /**
  12   * Controller which provides a REST endpoint for the editor to read registered
  13   * icons. Icons are grouped into collections (the default one being `core`).
  14   *
  15   * @since 7.0.0
  16   *
  17   * @see WP_REST_Controller
  18   */
  19  class WP_REST_Icons_Controller extends WP_REST_Controller {
  20  
  21      /**
  22       * Constructs the controller.
  23       *
  24       * @since 7.0.0
  25       */
  26  	public function __construct() {
  27          $this->namespace = 'wp/v2';
  28          $this->rest_base = 'icons';
  29      }
  30  
  31      /**
  32       * Registers the routes for the objects of the controller.
  33       *
  34       * @since 7.0.0
  35       * @since 7.1.0 Added the `/icons/<collection>` collection-scoped route.
  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<collection>[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)',
  55              array(
  56                  'args'   => array(
  57                      'collection' => array(
  58                          'description' => __( 'Icon collection slug.' ),
  59                          'type'        => 'string',
  60                      ),
  61                  ),
  62                  array(
  63                      'methods'             => WP_REST_Server::READABLE,
  64                      'callback'            => array( $this, 'get_items' ),
  65                      'permission_callback' => array( $this, 'get_items_permissions_check' ),
  66                      'args'                => $this->get_collection_params(),
  67                  ),
  68                  'schema' => array( $this, 'get_public_item_schema' ),
  69              )
  70          );
  71  
  72          register_rest_route(
  73              $this->namespace,
  74              '/' . $this->rest_base . '/(?P<name>[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?/[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)',
  75              array(
  76                  'args'   => array(
  77                      'name' => array(
  78                          'description' => __( 'Icon name.' ),
  79                          'type'        => 'string',
  80                      ),
  81                  ),
  82                  array(
  83                      'methods'             => WP_REST_Server::READABLE,
  84                      'callback'            => array( $this, 'get_item' ),
  85                      'permission_callback' => array( $this, 'get_item_permissions_check' ),
  86                      'args'                => array(
  87                          'context' => $this->get_context_param( array( 'default' => 'view' ) ),
  88                      ),
  89                  ),
  90                  'schema' => array( $this, 'get_public_item_schema' ),
  91              )
  92          );
  93      }
  94  
  95      /**
  96       * Checks whether a given request has permission to read icons.
  97       *
  98       * @since 7.0.0
  99       *
 100       * @param WP_REST_Request $request Full details about the request.
 101       * @return true|WP_Error True if the request has read access, WP_Error object otherwise.
 102       */
 103  	public function get_items_permissions_check(
 104          // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
 105          $request
 106      ) {
 107          if ( current_user_can( 'edit_posts' ) ) {
 108              return true;
 109          }
 110  
 111          foreach ( get_post_types( array( 'show_in_rest' => true ), 'objects' ) as $post_type ) {
 112              if ( current_user_can( $post_type->cap->edit_posts ) ) {
 113                  return true;
 114              }
 115          }
 116  
 117          return new WP_Error(
 118              'rest_cannot_view',
 119              __( 'Sorry, you are not allowed to view the registered icons.' ),
 120              array( 'status' => rest_authorization_required_code() )
 121          );
 122      }
 123  
 124      /**
 125       * Checks if a given request has access to read a specific icon.
 126       *
 127       * @since 7.0.0
 128       *
 129       * @param WP_REST_Request $request Full details about the request.
 130       * @return true|WP_Error True if the request has read access for the item, WP_Error object otherwise.
 131       */
 132  	public function get_item_permissions_check( $request ) {
 133          $check = $this->get_items_permissions_check( $request );
 134          if ( is_wp_error( $check ) ) {
 135              return $check;
 136          }
 137  
 138          return true;
 139      }
 140  
 141      /**
 142       * Retrieves all icons, optionally scoped to a collection.
 143       *
 144       * @since 7.0.0
 145       * @since 7.1.0 Supports filtering by collection.
 146       *
 147       * @param WP_REST_Request $request Full details about the request.
 148       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 149       */
 150  	public function get_items( $request ) {
 151          $collection = $request->get_param( 'collection' );
 152  
 153          if ( null !== $collection && ! WP_Icon_Collections_Registry::get_instance()->is_registered( $collection ) ) {
 154              return new WP_Error(
 155                  'rest_icon_collection_not_found',
 156                  sprintf(
 157                      /* translators: %s: Icon collection slug. */
 158                      __( 'Icon collection not found: "%s".' ),
 159                      $collection
 160                  ),
 161                  array( 'status' => 404 )
 162              );
 163          }
 164  
 165          $response = array();
 166          $search   = $request->get_param( 'search' );
 167          $icons    = WP_Icons_Registry::get_instance()->get_registered_icons( $search );
 168  
 169          foreach ( $icons as $icon ) {
 170              if ( null !== $collection && ( ! isset( $icon['collection'] ) || $icon['collection'] !== $collection ) ) {
 171                  continue;
 172              }
 173              $prepared_icon = $this->prepare_item_for_response( $icon, $request );
 174              $response[]    = $this->prepare_response_for_collection( $prepared_icon );
 175          }
 176          return rest_ensure_response( $response );
 177      }
 178  
 179      /**
 180       * Retrieves a specific icon.
 181       *
 182       * @since 7.0.0
 183       *
 184       * @param WP_REST_Request $request Full details about the request.
 185       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 186       */
 187  	public function get_item( $request ) {
 188          $icon = $this->get_icon( $request['name'] );
 189          if ( is_wp_error( $icon ) ) {
 190              return $icon;
 191          }
 192  
 193          $data = $this->prepare_item_for_response( $icon, $request );
 194          return rest_ensure_response( $data );
 195      }
 196  
 197      /**
 198       * Retrieves a specific icon from the registry.
 199       *
 200       * @since 7.0.0
 201       *
 202       * @param string $name Icon name.
 203       * @return array|WP_Error Icon data on success, or WP_Error object on failure.
 204       */
 205  	public function get_icon( $name ) {
 206          $registry = WP_Icons_Registry::get_instance();
 207          $icon     = $registry->get_registered_icon( $name );
 208  
 209          if ( null === $icon ) {
 210              return new WP_Error(
 211                  'rest_icon_not_found',
 212                  sprintf(
 213                      // translators: %s is the name of any user-provided name
 214                      __( 'Icon not found: "%s".' ),
 215                      $name
 216                  ),
 217                  array( 'status' => 404 )
 218              );
 219          }
 220  
 221          return $icon;
 222      }
 223  
 224      /**
 225       * Prepare a raw icon before it gets output in a REST API response.
 226       *
 227       * @since 7.0.0
 228       * @since 7.1.0 Added the `collection` field.
 229       *
 230       * @param array           $item    Raw icon as registered, before any changes.
 231       * @param WP_REST_Request $request Request object.
 232       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 233       */
 234  	public function prepare_item_for_response( $item, $request ) {
 235          $fields = $this->get_fields_for_response( $request );
 236          $keys   = array(
 237              'name'       => 'name',
 238              'label'      => 'label',
 239              'content'    => 'content',
 240              'collection' => 'collection',
 241          );
 242          $data   = array();
 243          foreach ( $keys as $item_key => $rest_key ) {
 244              if ( isset( $item[ $item_key ] ) && rest_is_field_included( $rest_key, $fields ) ) {
 245                  $data[ $rest_key ] = $item[ $item_key ];
 246              }
 247          }
 248  
 249          $context = ! empty( $request['context'] ) ? $request['context'] : 'view';
 250          $data    = $this->add_additional_fields_to_object( $data, $request );
 251          $data    = $this->filter_response_by_context( $data, $context );
 252          return rest_ensure_response( $data );
 253      }
 254  
 255      /**
 256       * Retrieves the icon schema, conforming to JSON Schema.
 257       *
 258       * @since 7.0.0
 259       * @since 7.1.0 Added the `collection` property.
 260       *
 261       * @return array Item schema data.
 262       */
 263  	public function get_item_schema() {
 264          if ( $this->schema ) {
 265              return $this->add_additional_fields_schema( $this->schema );
 266          }
 267  
 268          $schema = array(
 269              '$schema'    => 'http://json-schema.org/draft-04/schema#',
 270              'title'      => 'icon',
 271              'type'       => 'object',
 272              'properties' => array(
 273                  'name'       => array(
 274                      'description' => __( 'The icon name.' ),
 275                      'type'        => 'string',
 276                      'readonly'    => true,
 277                      'context'     => array( 'view', 'edit', 'embed' ),
 278                  ),
 279                  'label'      => array(
 280                      'description' => __( 'The icon label.' ),
 281                      'type'        => 'string',
 282                      'readonly'    => true,
 283                      'context'     => array( 'view', 'edit', 'embed' ),
 284                  ),
 285                  'content'    => array(
 286                      'description' => __( 'The icon content (SVG markup).' ),
 287                      'type'        => 'string',
 288                      'readonly'    => true,
 289                      'context'     => array( 'view', 'edit', 'embed' ),
 290                  ),
 291                  'collection' => array(
 292                      'description' => __( 'The slug of the collection this icon belongs to.' ),
 293                      'type'        => 'string',
 294                      'readonly'    => true,
 295                      'context'     => array( 'view', 'edit', 'embed' ),
 296                  ),
 297              ),
 298          );
 299  
 300          $this->schema = $schema;
 301  
 302          return $this->add_additional_fields_schema( $this->schema );
 303      }
 304  
 305      /**
 306       * Retrieves the query params for the icons collection.
 307       *
 308       * @since 7.0.0
 309       * @since 7.1.0 Added the `collection` parameter.
 310       *
 311       * @return array Collection parameters.
 312       */
 313  	public function get_collection_params() {
 314          $query_params                       = parent::get_collection_params();
 315          $query_params['context']['default'] = 'view';
 316          $query_params['collection']         = array(
 317              'description' => __( 'Limit results to icons belonging to the given collection slug.' ),
 318              'type'        => 'string',
 319              'pattern'     => '^[a-z0-9]([a-z0-9_-]*[a-z0-9])?$',
 320          );
 321          return $query_params;
 322      }
 323  }