class-wp-rest-block-directory-controller.php 9.7 KB

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