[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * REST API: WP_REST_Block_Directory_Controller class
   4   *
   5   * @package WordPress
   6   * @subpackage REST_API
   7   * @since 5.5.0
   8   */
   9  
  10  /**
  11   * Controller which provides REST endpoint for the blocks.
  12   *
  13   * @since 5.5.0
  14   *
  15   * @see WP_REST_Controller
  16   */
  17  class WP_REST_Block_Directory_Controller extends WP_REST_Controller {
  18  
  19      /**
  20       * Constructs the controller.
  21       */
  22  	public function __construct() {
  23          $this->namespace = 'wp/v2';
  24          $this->rest_base = 'block-directory';
  25      }
  26  
  27      /**
  28       * Registers the necessary REST API routes.
  29       */
  30  	public function register_routes() {
  31          register_rest_route(
  32              $this->namespace,
  33              '/' . $this->rest_base . '/search',
  34              array(
  35                  array(
  36                      'methods'             => WP_REST_Server::READABLE,
  37                      'callback'            => array( $this, 'get_items' ),
  38                      'permission_callback' => array( $this, 'get_items_permissions_check' ),
  39                      'args'                => $this->get_collection_params(),
  40                  ),
  41                  'schema' => array( $this, 'get_public_item_schema' ),
  42              )
  43          );
  44      }
  45  
  46      /**
  47       * Checks whether a given request has permission to install and activate plugins.
  48       *
  49       * @since 5.5.0
  50       *
  51       * @param WP_REST_Request $request Full details about the request.
  52       * @return true|WP_Error True if the request has permission, WP_Error object otherwise.
  53       */
  54  	public function get_items_permissions_check( $request ) {
  55          if ( ! current_user_can( 'install_plugins' ) || ! current_user_can( 'activate_plugins' ) ) {
  56              return new WP_Error(
  57                  'rest_block_directory_cannot_view',
  58                  __( 'Sorry, you are not allowed to browse the block directory.' ),
  59                  array( 'status' => rest_authorization_required_code() )
  60              );
  61          }
  62  
  63          return true;
  64      }
  65  
  66      /**
  67       * Search and retrieve blocks metadata
  68       *
  69       * @since 5.5.0
  70       *
  71       * @param WP_REST_Request $request Full details about the request.
  72       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
  73       */
  74  	public function get_items( $request ) {
  75          require_once  ABSPATH . 'wp-admin/includes/plugin-install.php';
  76          require_once  ABSPATH . 'wp-admin/includes/plugin.php';
  77  
  78          $response = plugins_api(
  79              'query_plugins',
  80              array(
  81                  'block'    => $request['term'],
  82                  'per_page' => $request['per_page'],
  83                  'page'     => $request['page'],
  84              )
  85          );
  86  
  87          if ( is_wp_error( $response ) ) {
  88              $response->add_data( array( 'status' => 500 ) );
  89  
  90              return $response;
  91          }
  92  
  93          $result = array();
  94  
  95          foreach ( $response->plugins as $plugin ) {
  96              // If the API returned a plugin with empty data for 'blocks', skip it.
  97              if ( empty( $plugin['blocks'] ) ) {
  98                  continue;
  99              }
 100  
 101              $data     = $this->prepare_item_for_response( $plugin, $request );
 102              $result[] = $this->prepare_response_for_collection( $data );
 103          }
 104  
 105          return rest_ensure_response( $result );
 106      }
 107  
 108      /**
 109       * Parse block metadata for a block, and prepare it for an API response.
 110       *
 111       * @since 5.5.0
 112       * @since 5.9.0 Renamed `$plugin` to `$item` to match parent class for PHP 8 named parameter support.
 113       *
 114       * @param array           $item    The plugin metadata.
 115       * @param WP_REST_Request $request Request object.
 116       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 117       */
 118  	public function prepare_item_for_response( $item, $request ) {
 119          // Restores the more descriptive, specific name for use within this method.
 120          $plugin = $item;
 121  
 122          $fields = $this->get_fields_for_response( $request );
 123  
 124          // There might be multiple blocks in a plugin. Only the first block is mapped.
 125          $block_data = reset( $plugin['blocks'] );
 126  
 127          // A data array containing the properties we'll return.
 128          $block = array(
 129              'name'                => $block_data['name'],
 130              'title'               => ( $block_data['title'] ? $block_data['title'] : $plugin['name'] ),
 131              'description'         => wp_trim_words( $plugin['short_description'], 30, '...' ),
 132              'id'                  => $plugin['slug'],
 133              'rating'              => $plugin['rating'] / 20,
 134              'rating_count'        => (int) $plugin['num_ratings'],
 135              'active_installs'     => (int) $plugin['active_installs'],
 136              'author_block_rating' => $plugin['author_block_rating'] / 20,
 137              'author_block_count'  => (int) $plugin['author_block_count'],
 138              'author'              => wp_strip_all_tags( $plugin['author'] ),
 139              'icon'                => $plugin['icons']['1x'] ?? 'block-default',
 140              'last_updated'        => gmdate( 'Y-m-d\TH:i:s', strtotime( $plugin['last_updated'] ) ),
 141              'humanized_updated'   => sprintf(
 142                  /* translators: %s: Human-readable time difference. */
 143                  __( '%s ago' ),
 144                  human_time_diff( strtotime( $plugin['last_updated'] ) )
 145              ),
 146          );
 147  
 148          $this->add_additional_fields_to_object( $block, $request );
 149  
 150          $response = new WP_REST_Response( $block );
 151  
 152          if ( rest_is_field_included( '_links', $fields ) || rest_is_field_included( '_embedded', $fields ) ) {
 153              $response->add_links( $this->prepare_links( $plugin ) );
 154          }
 155  
 156          return $response;
 157      }
 158  
 159      /**
 160       * Generates a list of links to include in the response for the plugin.
 161       *
 162       * @since 5.5.0
 163       *
 164       * @param array $plugin The plugin data from WordPress.org.
 165       * @return array
 166       */
 167  	protected function prepare_links( $plugin ) {
 168          $links = array(
 169              'https://api.w.org/install-plugin' => array(
 170                  'href' => add_query_arg( 'slug', urlencode( $plugin['slug'] ), rest_url( 'wp/v2/plugins' ) ),
 171              ),
 172          );
 173  
 174          $plugin_file = $this->find_plugin_for_slug( $plugin['slug'] );
 175  
 176          if ( $plugin_file ) {
 177              $links['https://api.w.org/plugin'] = array(
 178                  'href'       => rest_url( 'wp/v2/plugins/' . substr( $plugin_file, 0, - 4 ) ),
 179                  'embeddable' => true,
 180              );
 181          }
 182  
 183          return $links;
 184      }
 185  
 186      /**
 187       * Finds an installed plugin for the given slug.
 188       *
 189       * @since 5.5.0
 190       *
 191       * @param string $slug The WordPress.org directory slug for a plugin.
 192       * @return string The plugin file found matching it.
 193       */
 194  	protected function find_plugin_for_slug( $slug ) {
 195          require_once  ABSPATH . 'wp-admin/includes/plugin.php';
 196  
 197          $plugin_files = get_plugins( '/' . $slug );
 198  
 199          if ( ! $plugin_files ) {
 200              return '';
 201          }
 202  
 203          return $slug . '/' . array_key_first( $plugin_files );
 204      }
 205  
 206      /**
 207       * Retrieves the theme's schema, conforming to JSON Schema.
 208       *
 209       * @since 5.5.0
 210       *
 211       * @return array Item schema data.
 212       */
 213  	public function get_item_schema() {
 214          if ( $this->schema ) {
 215              return $this->add_additional_fields_schema( $this->schema );
 216          }
 217  
 218          $this->schema = array(
 219              '$schema'    => 'http://json-schema.org/draft-04/schema#',
 220              'title'      => 'block-directory-item',
 221              'type'       => 'object',
 222              'properties' => array(
 223                  'name'                => array(
 224                      'description' => __( 'The block name, in namespace/block-name format.' ),
 225                      'type'        => 'string',
 226                      'context'     => array( 'view' ),
 227                  ),
 228                  'title'               => array(
 229                      'description' => __( 'The block title, in human readable format.' ),
 230                      'type'        => 'string',
 231                      'context'     => array( 'view' ),
 232                  ),
 233                  'description'         => array(
 234                      'description' => __( 'A short description of the block, in human readable format.' ),
 235                      'type'        => 'string',
 236                      'context'     => array( 'view' ),
 237                  ),
 238                  'id'                  => array(
 239                      'description' => __( 'The block slug.' ),
 240                      'type'        => 'string',
 241                      'context'     => array( 'view' ),
 242                  ),
 243                  'rating'              => array(
 244                      'description' => __( 'The star rating of the block.' ),
 245                      'type'        => 'number',
 246                      'context'     => array( 'view' ),
 247                  ),
 248                  'rating_count'        => array(
 249                      'description' => __( 'The number of ratings.' ),
 250                      'type'        => 'integer',
 251                      'context'     => array( 'view' ),
 252                  ),
 253                  'active_installs'     => array(
 254                      'description' => __( 'The number sites that have activated this block.' ),
 255                      'type'        => 'integer',
 256                      'context'     => array( 'view' ),
 257                  ),
 258                  'author_block_rating' => array(
 259                      'description' => __( 'The average rating of blocks published by the same author.' ),
 260                      'type'        => 'number',
 261                      'context'     => array( 'view' ),
 262                  ),
 263                  'author_block_count'  => array(
 264                      'description' => __( 'The number of blocks published by the same author.' ),
 265                      'type'        => 'integer',
 266                      'context'     => array( 'view' ),
 267                  ),
 268                  'author'              => array(
 269                      'description' => __( 'The WordPress.org username of the block author.' ),
 270                      'type'        => 'string',
 271                      'context'     => array( 'view' ),
 272                  ),
 273                  'icon'                => array(
 274                      'description' => __( 'The block icon.' ),
 275                      'type'        => 'string',
 276                      'format'      => 'uri',
 277                      'context'     => array( 'view' ),
 278                  ),
 279                  'last_updated'        => array(
 280                      'description' => __( 'The date when the block was last updated.' ),
 281                      'type'        => 'string',
 282                      'format'      => 'date-time',
 283                      'context'     => array( 'view' ),
 284                  ),
 285                  'humanized_updated'   => array(
 286                      'description' => __( 'The date when the block was last updated, in human readable format.' ),
 287                      'type'        => 'string',
 288                      'context'     => array( 'view' ),
 289                  ),
 290              ),
 291          );
 292  
 293          return $this->add_additional_fields_schema( $this->schema );
 294      }
 295  
 296      /**
 297       * Retrieves the search params for the blocks collection.
 298       *
 299       * @since 5.5.0
 300       *
 301       * @return array Collection parameters.
 302       */
 303  	public function get_collection_params() {
 304          $query_params = parent::get_collection_params();
 305  
 306          $query_params['context']['default'] = 'view';
 307  
 308          $query_params['term'] = array(
 309              'description' => __( 'Limit result set to blocks matching the search term.' ),
 310              'type'        => 'string',
 311              'required'    => true,
 312              'minLength'   => 1,
 313          );
 314  
 315          unset( $query_params['search'] );
 316  
 317          /**
 318           * Filters REST API collection parameters for the block directory controller.
 319           *
 320           * @since 5.5.0
 321           *
 322           * @param array $query_params JSON Schema-formatted collection parameters.
 323           */
 324          return apply_filters( 'rest_block_directory_collection_params', $query_params );
 325      }
 326  }