[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       * @since 7.2.0 Icons registered as non-public are omitted.
 147       *
 148       * @param WP_REST_Request $request Full details about the request.
 149       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 150       */
 151  	public function get_items( $request ) {
 152          $collection = $request->get_param( 'collection' );
 153  
 154          if ( null !== $collection && ! WP_Icon_Collections_Registry::get_instance()->is_registered( $collection ) ) {
 155              return new WP_Error(
 156                  'rest_icon_collection_not_found',
 157                  sprintf(
 158                      /* translators: %s: Icon collection slug. */
 159                      __( 'Icon collection not found: "%s".' ),
 160                      $collection
 161                  ),
 162                  array( 'status' => 404 )
 163              );
 164          }
 165  
 166          $response = array();
 167          $search   = $request->get_param( 'search' );
 168          $icons    = WP_Icons_Registry::get_instance()->get_registered_icons( $search );
 169  
 170          foreach ( $icons as $icon ) {
 171              if ( false === ( $icon['public'] ?? true ) ) {
 172                  continue;
 173              }
 174              if ( null !== $collection && ( ! isset( $icon['collection'] ) || $icon['collection'] !== $collection ) ) {
 175                  continue;
 176              }
 177              $prepared_icon = $this->prepare_item_for_response( $icon, $request );
 178              $response[]    = $this->prepare_response_for_collection( $prepared_icon );
 179          }
 180          return rest_ensure_response( $response );
 181      }
 182  
 183      /**
 184       * Retrieves a specific icon.
 185       *
 186       * @since 7.0.0
 187       *
 188       * @param WP_REST_Request $request Full details about the request.
 189       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 190       */
 191  	public function get_item( $request ) {
 192          $icon = $this->get_icon( $request['name'] );
 193          if ( is_wp_error( $icon ) ) {
 194              return $icon;
 195          }
 196  
 197          $data = $this->prepare_item_for_response( $icon, $request );
 198          return rest_ensure_response( $data );
 199      }
 200  
 201      /**
 202       * Retrieves a specific icon from the registry.
 203       *
 204       * @since 7.0.0
 205       * @since 7.2.0 Icons registered as non-public are reported as not found.
 206       *
 207       * @param string $name Icon name.
 208       * @return array|WP_Error Icon data on success, or WP_Error object on failure.
 209       */
 210  	public function get_icon( $name ) {
 211          $registry = WP_Icons_Registry::get_instance();
 212          $icon     = $registry->get_registered_icon( $name );
 213  
 214          if ( null === $icon || false === ( $icon['public'] ?? true ) ) {
 215              return new WP_Error(
 216                  'rest_icon_not_found',
 217                  sprintf(
 218                      // translators: %s is the name of any user-provided name
 219                      __( 'Icon not found: "%s".' ),
 220                      $name
 221                  ),
 222                  array( 'status' => 404 )
 223              );
 224          }
 225  
 226          return $icon;
 227      }
 228  
 229      /**
 230       * Prepare a raw icon before it gets output in a REST API response.
 231       *
 232       * @since 7.0.0
 233       * @since 7.1.0 Added the `collection` field.
 234       *
 235       * @param array           $item    Raw icon as registered, before any changes.
 236       * @param WP_REST_Request $request Request object.
 237       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 238       */
 239  	public function prepare_item_for_response( $item, $request ) {
 240          $fields = $this->get_fields_for_response( $request );
 241          $keys   = array(
 242              'name'       => 'name',
 243              'label'      => 'label',
 244              'content'    => 'content',
 245              'collection' => 'collection',
 246          );
 247          $data   = array();
 248          foreach ( $keys as $item_key => $rest_key ) {
 249              if ( isset( $item[ $item_key ] ) && rest_is_field_included( $rest_key, $fields ) ) {
 250                  $data[ $rest_key ] = $item[ $item_key ];
 251              }
 252          }
 253  
 254          $context = ! empty( $request['context'] ) ? $request['context'] : 'view';
 255          $data    = $this->add_additional_fields_to_object( $data, $request );
 256          $data    = $this->filter_response_by_context( $data, $context );
 257          return rest_ensure_response( $data );
 258      }
 259  
 260      /**
 261       * Retrieves the icon schema, conforming to JSON Schema.
 262       *
 263       * @since 7.0.0
 264       * @since 7.1.0 Added the `collection` property.
 265       *
 266       * @return array Item schema data.
 267       */
 268  	public function get_item_schema() {
 269          if ( $this->schema ) {
 270              return $this->add_additional_fields_schema( $this->schema );
 271          }
 272  
 273          $schema = array(
 274              '$schema'    => 'http://json-schema.org/draft-04/schema#',
 275              'title'      => 'icon',
 276              'type'       => 'object',
 277              'properties' => array(
 278                  'name'       => array(
 279                      'description' => __( 'The icon name.' ),
 280                      'type'        => 'string',
 281                      'readonly'    => true,
 282                      'context'     => array( 'view', 'edit', 'embed' ),
 283                  ),
 284                  'label'      => array(
 285                      'description' => __( 'The icon label.' ),
 286                      'type'        => 'string',
 287                      'readonly'    => true,
 288                      'context'     => array( 'view', 'edit', 'embed' ),
 289                  ),
 290                  'content'    => array(
 291                      'description' => __( 'The icon content (SVG markup).' ),
 292                      'type'        => 'string',
 293                      'readonly'    => true,
 294                      'context'     => array( 'view', 'edit', 'embed' ),
 295                  ),
 296                  'collection' => array(
 297                      'description' => __( 'The slug of the collection this icon belongs to.' ),
 298                      'type'        => 'string',
 299                      'readonly'    => true,
 300                      'context'     => array( 'view', 'edit', 'embed' ),
 301                  ),
 302              ),
 303          );
 304  
 305          $this->schema = $schema;
 306  
 307          return $this->add_additional_fields_schema( $this->schema );
 308      }
 309  
 310      /**
 311       * Retrieves the query params for the icons collection.
 312       *
 313       * @since 7.0.0
 314       * @since 7.1.0 Added the `collection` parameter.
 315       *
 316       * @return array Collection parameters.
 317       */
 318  	public function get_collection_params() {
 319          $query_params                       = parent::get_collection_params();
 320          $query_params['context']['default'] = 'view';
 321          $query_params['collection']         = array(
 322              'description' => __( 'Limit results to icons belonging to the given collection slug.' ),
 323              'type'        => 'string',
 324              'pattern'     => '^[a-z0-9]([a-z0-9_-]*[a-z0-9])?$',
 325          );
 326          return $query_params;
 327      }
 328  }