[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/rest-api/endpoints/ -> class-wp-rest-terms-controller.php (source)

   1  <?php
   2  /**
   3   * REST API: WP_REST_Terms_Controller class
   4   *
   5   * @package WordPress
   6   * @subpackage REST_API
   7   * @since 4.7.0
   8   */
   9  
  10  /**
  11   * Core class used to managed terms associated with a taxonomy via the REST API.
  12   *
  13   * @since 4.7.0
  14   *
  15   * @see WP_REST_Controller
  16   */
  17  class WP_REST_Terms_Controller extends WP_REST_Controller {
  18  
  19      /**
  20       * Taxonomy key.
  21       *
  22       * @since 4.7.0
  23       * @var string
  24       */
  25      protected $taxonomy;
  26  
  27      /**
  28       * Instance of a term meta fields object.
  29       *
  30       * @since 4.7.0
  31       * @var WP_REST_Term_Meta_Fields
  32       */
  33      protected $meta;
  34  
  35      /**
  36       * Column to have the terms be sorted by.
  37       *
  38       * @since 4.7.0
  39       * @var string
  40       */
  41      protected $sort_column;
  42  
  43      /**
  44       * Number of terms that were found.
  45       *
  46       * @since 4.7.0
  47       * @var int
  48       */
  49      protected $total_terms;
  50  
  51      /**
  52       * Whether the controller supports batching.
  53       *
  54       * @since 5.9.0
  55       * @var array
  56       */
  57      protected $allow_batch = array( 'v1' => true );
  58  
  59      /**
  60       * Constructor.
  61       *
  62       * @since 4.7.0
  63       *
  64       * @param string $taxonomy Taxonomy key.
  65       */
  66  	public function __construct( $taxonomy ) {
  67          $this->taxonomy  = $taxonomy;
  68          $tax_obj         = get_taxonomy( $taxonomy );
  69          $this->rest_base = ! empty( $tax_obj->rest_base ) ? $tax_obj->rest_base : $tax_obj->name;
  70          $this->namespace = ! empty( $tax_obj->rest_namespace ) ? $tax_obj->rest_namespace : 'wp/v2';
  71  
  72          $this->meta = new WP_REST_Term_Meta_Fields( $taxonomy );
  73      }
  74  
  75      /**
  76       * Registers the routes for terms.
  77       *
  78       * @since 4.7.0
  79       *
  80       * @see register_rest_route()
  81       */
  82  	public function register_routes() {
  83  
  84          register_rest_route(
  85              $this->namespace,
  86              '/' . $this->rest_base,
  87              array(
  88                  array(
  89                      'methods'             => WP_REST_Server::READABLE,
  90                      'callback'            => array( $this, 'get_items' ),
  91                      'permission_callback' => array( $this, 'get_items_permissions_check' ),
  92                      'args'                => $this->get_collection_params(),
  93                  ),
  94                  array(
  95                      'methods'             => WP_REST_Server::CREATABLE,
  96                      'callback'            => array( $this, 'create_item' ),
  97                      'permission_callback' => array( $this, 'create_item_permissions_check' ),
  98                      'args'                => $this->get_endpoint_args_for_item_schema( WP_REST_Server::CREATABLE ),
  99                  ),
 100                  'allow_batch' => $this->allow_batch,
 101                  'schema'      => array( $this, 'get_public_item_schema' ),
 102              )
 103          );
 104  
 105          register_rest_route(
 106              $this->namespace,
 107              '/' . $this->rest_base . '/(?P<id>[\d]+)',
 108              array(
 109                  'args'        => array(
 110                      'id' => array(
 111                          'description' => __( 'Unique identifier for the term.' ),
 112                          'type'        => 'integer',
 113                      ),
 114                  ),
 115                  array(
 116                      'methods'             => WP_REST_Server::READABLE,
 117                      'callback'            => array( $this, 'get_item' ),
 118                      'permission_callback' => array( $this, 'get_item_permissions_check' ),
 119                      'args'                => array(
 120                          'context' => $this->get_context_param( array( 'default' => 'view' ) ),
 121                      ),
 122                  ),
 123                  array(
 124                      'methods'             => WP_REST_Server::EDITABLE,
 125                      'callback'            => array( $this, 'update_item' ),
 126                      'permission_callback' => array( $this, 'update_item_permissions_check' ),
 127                      'args'                => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ),
 128                  ),
 129                  array(
 130                      'methods'             => WP_REST_Server::DELETABLE,
 131                      'callback'            => array( $this, 'delete_item' ),
 132                      'permission_callback' => array( $this, 'delete_item_permissions_check' ),
 133                      'args'                => array(
 134                          'force' => array(
 135                              'type'        => 'boolean',
 136                              'default'     => false,
 137                              'description' => __( 'Required to be true, as terms do not support trashing.' ),
 138                          ),
 139                      ),
 140                  ),
 141                  'allow_batch' => $this->allow_batch,
 142                  'schema'      => array( $this, 'get_public_item_schema' ),
 143              )
 144          );
 145      }
 146  
 147      /**
 148       * Checks if the terms for a post can be read.
 149       *
 150       * @since 6.0.3
 151       *
 152       * @param WP_Post         $post    Post object.
 153       * @param WP_REST_Request $request Full details about the request.
 154       * @return bool Whether the terms for the post can be read.
 155       */
 156  	public function check_read_terms_permission_for_post( $post, $request ) {
 157          // If the requested post isn't associated with this taxonomy, deny access.
 158          if ( ! is_object_in_taxonomy( $post->post_type, $this->taxonomy ) ) {
 159              return false;
 160          }
 161  
 162          // Grant access if the post is publicly viewable.
 163          if ( is_post_publicly_viewable( $post ) ) {
 164              return true;
 165          }
 166  
 167          // Otherwise grant access if the post is readable by the logged-in user.
 168          if ( current_user_can( 'read_post', $post->ID ) ) {
 169              return true;
 170          }
 171  
 172          // Otherwise, deny access.
 173          return false;
 174      }
 175  
 176      /**
 177       * Checks if a request has access to read terms in the specified taxonomy.
 178       *
 179       * @since 4.7.0
 180       *
 181       * @param WP_REST_Request $request Full details about the request.
 182       * @return bool|WP_Error True if the request has read access, otherwise false or WP_Error object.
 183       */
 184  	public function get_items_permissions_check( $request ) {
 185          $tax_obj = get_taxonomy( $this->taxonomy );
 186  
 187          if ( ! $tax_obj || ! $this->check_is_taxonomy_allowed( $this->taxonomy ) ) {
 188              return false;
 189          }
 190  
 191          if ( 'edit' === $request['context'] && ! current_user_can( $tax_obj->cap->edit_terms ) ) {
 192              return new WP_Error(
 193                  'rest_forbidden_context',
 194                  __( 'Sorry, you are not allowed to edit terms in this taxonomy.' ),
 195                  array( 'status' => rest_authorization_required_code() )
 196              );
 197          }
 198  
 199          if ( ! empty( $request['post'] ) ) {
 200              $post = get_post( $request['post'] );
 201  
 202              if ( ! $post ) {
 203                  return new WP_Error(
 204                      'rest_post_invalid_id',
 205                      __( 'Invalid post ID.' ),
 206                      array(
 207                          'status' => 400,
 208                      )
 209                  );
 210              }
 211  
 212              if ( ! $this->check_read_terms_permission_for_post( $post, $request ) ) {
 213                  return new WP_Error(
 214                      'rest_forbidden_context',
 215                      __( 'Sorry, you are not allowed to view terms for this post.' ),
 216                      array(
 217                          'status' => rest_authorization_required_code(),
 218                      )
 219                  );
 220              }
 221          }
 222  
 223          return true;
 224      }
 225  
 226      /**
 227       * Retrieves terms associated with a taxonomy.
 228       *
 229       * @since 4.7.0
 230       * @since 6.8.0 Respect default query arguments set for the taxonomy upon registration.
 231       *
 232       * @param WP_REST_Request $request Full details about the request.
 233       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 234       */
 235  	public function get_items( $request ) {
 236  
 237          // Retrieve the list of registered collection query parameters.
 238          $registered = $this->get_collection_params();
 239  
 240          /*
 241           * This array defines mappings between public API query parameters whose
 242           * values are accepted as-passed, and their internal WP_Query parameter
 243           * name equivalents (some are the same). Only values which are also
 244           * present in $registered will be set.
 245           */
 246          $parameter_mappings = array(
 247              'exclude'    => 'exclude',
 248              'include'    => 'include',
 249              'order'      => 'order',
 250              'orderby'    => 'orderby',
 251              'post'       => 'post',
 252              'hide_empty' => 'hide_empty',
 253              'per_page'   => 'number',
 254              'search'     => 'search',
 255              'slug'       => 'slug',
 256          );
 257  
 258          $prepared_args = array( 'taxonomy' => $this->taxonomy );
 259  
 260          /*
 261           * For each known parameter which is both registered and present in the request,
 262           * set the parameter's value on the query $prepared_args.
 263           */
 264          foreach ( $parameter_mappings as $api_param => $wp_param ) {
 265              if ( isset( $registered[ $api_param ], $request[ $api_param ] ) ) {
 266                  $prepared_args[ $wp_param ] = $request[ $api_param ];
 267              }
 268          }
 269  
 270          if ( isset( $prepared_args['orderby'] ) && isset( $request['orderby'] ) ) {
 271              $orderby_mappings = array(
 272                  'include_slugs' => 'slug__in',
 273              );
 274  
 275              if ( isset( $orderby_mappings[ $request['orderby'] ] ) ) {
 276                  $prepared_args['orderby'] = $orderby_mappings[ $request['orderby'] ];
 277              }
 278          }
 279  
 280          if ( isset( $registered['offset'] ) && ! empty( $request['offset'] ) ) {
 281              $prepared_args['offset'] = $request['offset'];
 282          } else {
 283              $prepared_args['offset'] = ( $request['page'] - 1 ) * $prepared_args['number'];
 284          }
 285  
 286          $taxonomy_obj = get_taxonomy( $this->taxonomy );
 287  
 288          if ( $taxonomy_obj->hierarchical && isset( $registered['parent'], $request['parent'] ) ) {
 289              if ( 0 === $request['parent'] ) {
 290                  // Only query top-level terms.
 291                  $prepared_args['parent'] = 0;
 292              } else {
 293                  if ( $request['parent'] ) {
 294                      $prepared_args['parent'] = $request['parent'];
 295                  }
 296              }
 297          }
 298  
 299          /*
 300           * When a taxonomy is registered with an 'args' array,
 301           * those params override the `$args` passed to this function.
 302           *
 303           * We only need to do this if no `post` argument is provided.
 304           * Otherwise, terms will be fetched using `wp_get_object_terms()`,
 305           * which respects the default query arguments set for the taxonomy.
 306           */
 307          if (
 308              empty( $prepared_args['post'] ) &&
 309              isset( $taxonomy_obj->args ) &&
 310              is_array( $taxonomy_obj->args )
 311          ) {
 312              $prepared_args = array_merge( $prepared_args, $taxonomy_obj->args );
 313          }
 314  
 315          /**
 316           * Filters get_terms() arguments when querying terms via the REST API.
 317           *
 318           * The dynamic portion of the hook name, `$this->taxonomy`, refers to the taxonomy slug.
 319           *
 320           * Possible hook names include:
 321           *
 322           *  - `rest_category_query`
 323           *  - `rest_post_tag_query`
 324           *
 325           * Enables adding extra arguments or setting defaults for a terms
 326           * collection request.
 327           *
 328           * @since 4.7.0
 329           *
 330           * @link https://developer.wordpress.org/reference/functions/get_terms/
 331           *
 332           * @param array           $prepared_args Array of arguments for get_terms().
 333           * @param WP_REST_Request $request       The REST API request.
 334           */
 335          $prepared_args = apply_filters( "rest_{$this->taxonomy}_query", $prepared_args, $request );
 336  
 337          if ( ! empty( $prepared_args['post'] ) ) {
 338              $query_result = wp_get_object_terms( $prepared_args['post'], $this->taxonomy, $prepared_args );
 339  
 340              // Used when calling wp_count_terms() below.
 341              $prepared_args['object_ids'] = $prepared_args['post'];
 342          } else {
 343              $query_result = get_terms( $prepared_args );
 344          }
 345  
 346          $count_args = $prepared_args;
 347  
 348          unset( $count_args['number'], $count_args['offset'] );
 349  
 350          $total_terms = wp_count_terms( $count_args );
 351  
 352          // wp_count_terms() can return a falsey value when the term has no children.
 353          if ( ! $total_terms ) {
 354              $total_terms = 0;
 355          }
 356  
 357          $response = array();
 358  
 359          foreach ( $query_result as $term ) {
 360              $data       = $this->prepare_item_for_response( $term, $request );
 361              $response[] = $this->prepare_response_for_collection( $data );
 362          }
 363  
 364          $response = rest_ensure_response( $response );
 365  
 366          // Store pagination values for headers.
 367          $per_page = (int) $prepared_args['number'];
 368          $page     = (int) ceil( ( ( (int) $prepared_args['offset'] ) / $per_page ) + 1 );
 369  
 370          $response->header( 'X-WP-Total', (int) $total_terms );
 371  
 372          $max_pages = (int) ceil( $total_terms / $per_page );
 373  
 374          $response->header( 'X-WP-TotalPages', $max_pages );
 375  
 376          $request_params = $request->get_query_params();
 377          $collection_url = rest_url( rest_get_route_for_taxonomy_items( $this->taxonomy ) );
 378          $base           = add_query_arg( urlencode_deep( $request_params ), $collection_url );
 379  
 380          if ( $page > 1 ) {
 381              $prev_page = $page - 1;
 382  
 383              if ( $prev_page > $max_pages ) {
 384                  $prev_page = $max_pages;
 385              }
 386  
 387              $prev_link = add_query_arg( 'page', $prev_page, $base );
 388              $response->link_header( 'prev', $prev_link );
 389          }
 390          if ( $max_pages > $page ) {
 391              $next_page = $page + 1;
 392              $next_link = add_query_arg( 'page', $next_page, $base );
 393  
 394              $response->link_header( 'next', $next_link );
 395          }
 396  
 397          return $response;
 398      }
 399  
 400      /**
 401       * Get the term, if the ID is valid.
 402       *
 403       * @since 4.7.2
 404       *
 405       * @param int $id Supplied ID.
 406       * @return WP_Term|WP_Error Term object if ID is valid, WP_Error otherwise.
 407       */
 408  	protected function get_term( $id ) {
 409          $error = new WP_Error(
 410              'rest_term_invalid',
 411              __( 'Term does not exist.' ),
 412              array( 'status' => 404 )
 413          );
 414  
 415          if ( ! $this->check_is_taxonomy_allowed( $this->taxonomy ) ) {
 416              return $error;
 417          }
 418  
 419          if ( (int) $id <= 0 ) {
 420              return $error;
 421          }
 422  
 423          $term = get_term( (int) $id, $this->taxonomy );
 424          if ( empty( $term ) || $term->taxonomy !== $this->taxonomy ) {
 425              return $error;
 426          }
 427  
 428          return $term;
 429      }
 430  
 431      /**
 432       * Checks if a request has access to read or edit the specified term.
 433       *
 434       * @since 4.7.0
 435       *
 436       * @param WP_REST_Request $request Full details about the request.
 437       * @return true|WP_Error True if the request has read access for the item, otherwise WP_Error object.
 438       */
 439  	public function get_item_permissions_check( $request ) {
 440          $term = $this->get_term( $request['id'] );
 441  
 442          if ( is_wp_error( $term ) ) {
 443              return $term;
 444          }
 445  
 446          if ( 'edit' === $request['context'] && ! current_user_can( 'edit_term', $term->term_id ) ) {
 447              return new WP_Error(
 448                  'rest_forbidden_context',
 449                  __( 'Sorry, you are not allowed to edit this term.' ),
 450                  array( 'status' => rest_authorization_required_code() )
 451              );
 452          }
 453  
 454          return true;
 455      }
 456  
 457      /**
 458       * Gets a single term from a taxonomy.
 459       *
 460       * @since 4.7.0
 461       *
 462       * @param WP_REST_Request $request Full details about the request.
 463       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 464       */
 465  	public function get_item( $request ) {
 466          $term = $this->get_term( $request['id'] );
 467          if ( is_wp_error( $term ) ) {
 468              return $term;
 469          }
 470  
 471          $response = $this->prepare_item_for_response( $term, $request );
 472  
 473          return rest_ensure_response( $response );
 474      }
 475  
 476      /**
 477       * Checks if a request has access to create a term.
 478       *
 479       * @since 4.7.0
 480       *
 481       * @param WP_REST_Request $request Full details about the request.
 482       * @return bool|WP_Error True if the request has access to create items, otherwise false or WP_Error object.
 483       */
 484  	public function create_item_permissions_check( $request ) {
 485  
 486          if ( ! $this->check_is_taxonomy_allowed( $this->taxonomy ) ) {
 487              return false;
 488          }
 489  
 490          $taxonomy_obj = get_taxonomy( $this->taxonomy );
 491  
 492          if ( ( is_taxonomy_hierarchical( $this->taxonomy )
 493                  && ! current_user_can( $taxonomy_obj->cap->edit_terms ) )
 494              || ( ! is_taxonomy_hierarchical( $this->taxonomy )
 495                  && ! current_user_can( $taxonomy_obj->cap->assign_terms ) ) ) {
 496              return new WP_Error(
 497                  'rest_cannot_create',
 498                  __( 'Sorry, you are not allowed to create terms in this taxonomy.' ),
 499                  array( 'status' => rest_authorization_required_code() )
 500              );
 501          }
 502  
 503          return true;
 504      }
 505  
 506      /**
 507       * Creates a single term in a taxonomy.
 508       *
 509       * @since 4.7.0
 510       *
 511       * @param WP_REST_Request $request Full details about the request.
 512       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 513       */
 514  	public function create_item( $request ) {
 515          if ( isset( $request['parent'] ) ) {
 516              if ( ! is_taxonomy_hierarchical( $this->taxonomy ) ) {
 517                  return new WP_Error(
 518                      'rest_taxonomy_not_hierarchical',
 519                      __( 'Cannot set parent term, taxonomy is not hierarchical.' ),
 520                      array( 'status' => 400 )
 521                  );
 522              }
 523  
 524              $parent = get_term( (int) $request['parent'], $this->taxonomy );
 525  
 526              if ( ! $parent ) {
 527                  return new WP_Error(
 528                      'rest_term_invalid',
 529                      __( 'Parent term does not exist.' ),
 530                      array( 'status' => 400 )
 531                  );
 532              }
 533          }
 534  
 535          $prepared_term = $this->prepare_item_for_database( $request );
 536  
 537          $term = wp_insert_term( wp_slash( $prepared_term->name ), $this->taxonomy, wp_slash( (array) $prepared_term ) );
 538          if ( is_wp_error( $term ) ) {
 539              /*
 540               * If we're going to inform the client that the term already exists,
 541               * give them the identifier for future use.
 542               */
 543              $term_id = $term->get_error_data( 'term_exists' );
 544              if ( $term_id ) {
 545                  $existing_term = get_term( $term_id, $this->taxonomy );
 546                  $term->add_data( $existing_term->term_id, 'term_exists' );
 547                  $term->add_data(
 548                      array(
 549                          'status'  => 400,
 550                          'term_id' => $term_id,
 551                      )
 552                  );
 553              }
 554  
 555              return $term;
 556          }
 557  
 558          $term = get_term( $term['term_id'], $this->taxonomy );
 559  
 560          /**
 561           * Fires after a single term is created or updated via the REST API.
 562           *
 563           * The dynamic portion of the hook name, `$this->taxonomy`, refers to the taxonomy slug.
 564           *
 565           * Possible hook names include:
 566           *
 567           *  - `rest_insert_category`
 568           *  - `rest_insert_post_tag`
 569           *
 570           * @since 4.7.0
 571           *
 572           * @param WP_Term         $term     Inserted or updated term object.
 573           * @param WP_REST_Request $request  Request object.
 574           * @param bool            $creating True when creating a term, false when updating.
 575           */
 576          do_action( "rest_insert_{$this->taxonomy}", $term, $request, true );
 577  
 578          $schema = $this->get_item_schema();
 579          if ( ! empty( $schema['properties']['meta'] ) && isset( $request['meta'] ) ) {
 580              $meta_update = $this->meta->update_value( $request['meta'], $term->term_id );
 581  
 582              if ( is_wp_error( $meta_update ) ) {
 583                  return $meta_update;
 584              }
 585          }
 586  
 587          $fields_update = $this->update_additional_fields_for_object( $term, $request );
 588  
 589          if ( is_wp_error( $fields_update ) ) {
 590              return $fields_update;
 591          }
 592  
 593          $request->set_param( 'context', 'edit' );
 594  
 595          /**
 596           * Fires after a single term is completely created or updated via the REST API.
 597           *
 598           * The dynamic portion of the hook name, `$this->taxonomy`, refers to the taxonomy slug.
 599           *
 600           * Possible hook names include:
 601           *
 602           *  - `rest_after_insert_category`
 603           *  - `rest_after_insert_post_tag`
 604           *
 605           * @since 5.0.0
 606           *
 607           * @param WP_Term         $term     Inserted or updated term object.
 608           * @param WP_REST_Request $request  Request object.
 609           * @param bool            $creating True when creating a term, false when updating.
 610           */
 611          do_action( "rest_after_insert_{$this->taxonomy}", $term, $request, true );
 612  
 613          $response = $this->prepare_item_for_response( $term, $request );
 614          $response = rest_ensure_response( $response );
 615  
 616          $response->set_status( 201 );
 617          $response->header( 'Location', rest_url( $this->namespace . '/' . $this->rest_base . '/' . $term->term_id ) );
 618  
 619          return $response;
 620      }
 621  
 622      /**
 623       * Checks if a request has access to update the specified term.
 624       *
 625       * @since 4.7.0
 626       *
 627       * @param WP_REST_Request $request Full details about the request.
 628       * @return true|WP_Error True if the request has access to update the item, false or WP_Error object otherwise.
 629       */
 630  	public function update_item_permissions_check( $request ) {
 631          $term = $this->get_term( $request['id'] );
 632  
 633          if ( is_wp_error( $term ) ) {
 634              return $term;
 635          }
 636  
 637          if ( ! current_user_can( 'edit_term', $term->term_id ) ) {
 638              return new WP_Error(
 639                  'rest_cannot_update',
 640                  __( 'Sorry, you are not allowed to edit this term.' ),
 641                  array( 'status' => rest_authorization_required_code() )
 642              );
 643          }
 644  
 645          return true;
 646      }
 647  
 648      /**
 649       * Updates a single term from a taxonomy.
 650       *
 651       * @since 4.7.0
 652       *
 653       * @param WP_REST_Request $request Full details about the request.
 654       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 655       */
 656  	public function update_item( $request ) {
 657          $term = $this->get_term( $request['id'] );
 658          if ( is_wp_error( $term ) ) {
 659              return $term;
 660          }
 661  
 662          if ( isset( $request['parent'] ) ) {
 663              if ( ! is_taxonomy_hierarchical( $this->taxonomy ) ) {
 664                  return new WP_Error(
 665                      'rest_taxonomy_not_hierarchical',
 666                      __( 'Cannot set parent term, taxonomy is not hierarchical.' ),
 667                      array( 'status' => 400 )
 668                  );
 669              }
 670  
 671              $parent = get_term( (int) $request['parent'], $this->taxonomy );
 672  
 673              if ( ! $parent ) {
 674                  return new WP_Error(
 675                      'rest_term_invalid',
 676                      __( 'Parent term does not exist.' ),
 677                      array( 'status' => 400 )
 678                  );
 679              }
 680          }
 681  
 682          $prepared_term = $this->prepare_item_for_database( $request );
 683  
 684          // Only update the term if we have something to update.
 685          if ( ! empty( $prepared_term ) ) {
 686              $update = wp_update_term( $term->term_id, $term->taxonomy, wp_slash( (array) $prepared_term ) );
 687  
 688              if ( is_wp_error( $update ) ) {
 689                  return $update;
 690              }
 691          }
 692  
 693          $term = get_term( $term->term_id, $this->taxonomy );
 694  
 695          /** This action is documented in wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php */
 696          do_action( "rest_insert_{$this->taxonomy}", $term, $request, false );
 697  
 698          $schema = $this->get_item_schema();
 699          if ( ! empty( $schema['properties']['meta'] ) && isset( $request['meta'] ) ) {
 700              $meta_update = $this->meta->update_value( $request['meta'], $term->term_id );
 701  
 702              if ( is_wp_error( $meta_update ) ) {
 703                  return $meta_update;
 704              }
 705          }
 706  
 707          $fields_update = $this->update_additional_fields_for_object( $term, $request );
 708  
 709          if ( is_wp_error( $fields_update ) ) {
 710              return $fields_update;
 711          }
 712  
 713          $request->set_param( 'context', 'edit' );
 714  
 715          /** This action is documented in wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php */
 716          do_action( "rest_after_insert_{$this->taxonomy}", $term, $request, false );
 717  
 718          $response = $this->prepare_item_for_response( $term, $request );
 719  
 720          return rest_ensure_response( $response );
 721      }
 722  
 723      /**
 724       * Checks if a request has access to delete the specified term.
 725       *
 726       * @since 4.7.0
 727       *
 728       * @param WP_REST_Request $request Full details about the request.
 729       * @return true|WP_Error True if the request has access to delete the item, otherwise false or WP_Error object.
 730       */
 731  	public function delete_item_permissions_check( $request ) {
 732          $term = $this->get_term( $request['id'] );
 733  
 734          if ( is_wp_error( $term ) ) {
 735              return $term;
 736          }
 737  
 738          if ( ! current_user_can( 'delete_term', $term->term_id ) ) {
 739              return new WP_Error(
 740                  'rest_cannot_delete',
 741                  __( 'Sorry, you are not allowed to delete this term.' ),
 742                  array( 'status' => rest_authorization_required_code() )
 743              );
 744          }
 745  
 746          return true;
 747      }
 748  
 749      /**
 750       * Deletes a single term from a taxonomy.
 751       *
 752       * @since 4.7.0
 753       *
 754       * @param WP_REST_Request $request Full details about the request.
 755       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 756       */
 757  	public function delete_item( $request ) {
 758          $term = $this->get_term( $request['id'] );
 759          if ( is_wp_error( $term ) ) {
 760              return $term;
 761          }
 762  
 763          $force = isset( $request['force'] ) ? (bool) $request['force'] : false;
 764  
 765          // We don't support trashing for terms.
 766          if ( ! $force ) {
 767              return new WP_Error(
 768                  'rest_trash_not_supported',
 769                  /* translators: %s: force=true */
 770                  sprintf( __( "Terms do not support trashing. Set '%s' to delete." ), 'force=true' ),
 771                  array( 'status' => 501 )
 772              );
 773          }
 774  
 775          $request->set_param( 'context', 'view' );
 776  
 777          $previous = $this->prepare_item_for_response( $term, $request );
 778  
 779          $retval = wp_delete_term( $term->term_id, $term->taxonomy );
 780  
 781          if ( ! $retval ) {
 782              return new WP_Error(
 783                  'rest_cannot_delete',
 784                  __( 'The term cannot be deleted.' ),
 785                  array( 'status' => 500 )
 786              );
 787          }
 788  
 789          $response = new WP_REST_Response();
 790          $response->set_data(
 791              array(
 792                  'deleted'  => true,
 793                  'previous' => $previous->get_data(),
 794              )
 795          );
 796  
 797          /**
 798           * Fires after a single term is deleted via the REST API.
 799           *
 800           * The dynamic portion of the hook name, `$this->taxonomy`, refers to the taxonomy slug.
 801           *
 802           * Possible hook names include:
 803           *
 804           *  - `rest_delete_category`
 805           *  - `rest_delete_post_tag`
 806           *
 807           * @since 4.7.0
 808           *
 809           * @param WP_Term          $term     The deleted term.
 810           * @param WP_REST_Response $response The response data.
 811           * @param WP_REST_Request  $request  The request sent to the API.
 812           */
 813          do_action( "rest_delete_{$this->taxonomy}", $term, $response, $request );
 814  
 815          return $response;
 816      }
 817  
 818      /**
 819       * Prepares a single term for create or update.
 820       *
 821       * @since 4.7.0
 822       *
 823       * @param WP_REST_Request $request Request object.
 824       * @return object Term object.
 825       */
 826  	public function prepare_item_for_database( $request ) {
 827          $prepared_term = new stdClass();
 828  
 829          $schema = $this->get_item_schema();
 830          if ( isset( $request['name'] ) && ! empty( $schema['properties']['name'] ) ) {
 831              $prepared_term->name = $request['name'];
 832          }
 833  
 834          if ( isset( $request['slug'] ) && ! empty( $schema['properties']['slug'] ) ) {
 835              $prepared_term->slug = $request['slug'];
 836          }
 837  
 838          if ( isset( $request['taxonomy'] ) && ! empty( $schema['properties']['taxonomy'] ) ) {
 839              $prepared_term->taxonomy = $request['taxonomy'];
 840          }
 841  
 842          if ( isset( $request['description'] ) && ! empty( $schema['properties']['description'] ) ) {
 843              $prepared_term->description = $request['description'];
 844          }
 845  
 846          if ( isset( $request['parent'] ) && ! empty( $schema['properties']['parent'] ) ) {
 847              $parent_term_id   = 0;
 848              $requested_parent = (int) $request['parent'];
 849  
 850              if ( $requested_parent ) {
 851                  $parent_term = get_term( $requested_parent, $this->taxonomy );
 852  
 853                  if ( $parent_term instanceof WP_Term ) {
 854                      $parent_term_id = $parent_term->term_id;
 855                  }
 856              }
 857  
 858              $prepared_term->parent = $parent_term_id;
 859          }
 860  
 861          /**
 862           * Filters term data before inserting term via the REST API.
 863           *
 864           * The dynamic portion of the hook name, `$this->taxonomy`, refers to the taxonomy slug.
 865           *
 866           * Possible hook names include:
 867           *
 868           *  - `rest_pre_insert_category`
 869           *  - `rest_pre_insert_post_tag`
 870           *
 871           * @since 4.7.0
 872           *
 873           * @param object          $prepared_term Term object.
 874           * @param WP_REST_Request $request       Request object.
 875           */
 876          return apply_filters( "rest_pre_insert_{$this->taxonomy}", $prepared_term, $request );
 877      }
 878  
 879      /**
 880       * Prepares a single term output for response.
 881       *
 882       * @since 4.7.0
 883       *
 884       * @param WP_Term         $item    Term object.
 885       * @param WP_REST_Request $request Request object.
 886       * @return WP_REST_Response Response object.
 887       */
 888  	public function prepare_item_for_response( $item, $request ) {
 889  
 890          $fields = $this->get_fields_for_response( $request );
 891          $data   = array();
 892  
 893          if ( in_array( 'id', $fields, true ) ) {
 894              $data['id'] = (int) $item->term_id;
 895          }
 896  
 897          if ( in_array( 'count', $fields, true ) ) {
 898              $data['count'] = (int) $item->count;
 899          }
 900  
 901          if ( in_array( 'description', $fields, true ) ) {
 902              $data['description'] = $item->description;
 903          }
 904  
 905          if ( in_array( 'link', $fields, true ) ) {
 906              $data['link'] = get_term_link( $item );
 907          }
 908  
 909          if ( in_array( 'name', $fields, true ) ) {
 910              $data['name'] = $item->name;
 911          }
 912  
 913          if ( in_array( 'slug', $fields, true ) ) {
 914              $data['slug'] = $item->slug;
 915          }
 916  
 917          if ( in_array( 'taxonomy', $fields, true ) ) {
 918              $data['taxonomy'] = $item->taxonomy;
 919          }
 920  
 921          if ( in_array( 'parent', $fields, true ) ) {
 922              $data['parent'] = (int) $item->parent;
 923          }
 924  
 925          if ( in_array( 'meta', $fields, true ) ) {
 926              $data['meta'] = $this->meta->get_value( $item->term_id, $request );
 927          }
 928  
 929          $context = ! empty( $request['context'] ) ? $request['context'] : 'view';
 930          $data    = $this->add_additional_fields_to_object( $data, $request );
 931          $data    = $this->filter_response_by_context( $data, $context );
 932  
 933          $response = rest_ensure_response( $data );
 934  
 935          if ( rest_is_field_included( '_links', $fields ) || rest_is_field_included( '_embedded', $fields ) ) {
 936              $response->add_links( $this->prepare_links( $item ) );
 937          }
 938  
 939          /**
 940           * Filters the term data for a REST API response.
 941           *
 942           * The dynamic portion of the hook name, `$this->taxonomy`, refers to the taxonomy slug.
 943           *
 944           * Possible hook names include:
 945           *
 946           *  - `rest_prepare_category`
 947           *  - `rest_prepare_post_tag`
 948           *
 949           * Allows modification of the term data right before it is returned.
 950           *
 951           * @since 4.7.0
 952           *
 953           * @param WP_REST_Response  $response  The response object.
 954           * @param WP_Term           $item      The original term object.
 955           * @param WP_REST_Request   $request   Request used to generate the response.
 956           */
 957          return apply_filters( "rest_prepare_{$this->taxonomy}", $response, $item, $request );
 958      }
 959  
 960      /**
 961       * Prepares links for the request.
 962       *
 963       * @since 4.7.0
 964       *
 965       * @param WP_Term $term Term object.
 966       * @return array Links for the given term.
 967       */
 968  	protected function prepare_links( $term ) {
 969          $links = array(
 970              'self'       => array(
 971                  'href' => rest_url( rest_get_route_for_term( $term ) ),
 972              ),
 973              'collection' => array(
 974                  'href' => rest_url( rest_get_route_for_taxonomy_items( $this->taxonomy ) ),
 975              ),
 976              'about'      => array(
 977                  'href' => rest_url( sprintf( 'wp/v2/taxonomies/%s', $this->taxonomy ) ),
 978              ),
 979          );
 980  
 981          if ( $term->parent ) {
 982              $parent_term = get_term( (int) $term->parent, $term->taxonomy );
 983  
 984              if ( $parent_term ) {
 985                  $links['up'] = array(
 986                      'href'       => rest_url( rest_get_route_for_term( $parent_term ) ),
 987                      'embeddable' => true,
 988                  );
 989              }
 990          }
 991  
 992          $taxonomy_obj = get_taxonomy( $term->taxonomy );
 993  
 994          if ( empty( $taxonomy_obj->object_type ) ) {
 995              return $links;
 996          }
 997  
 998          $post_type_links = array();
 999  
1000          foreach ( $taxonomy_obj->object_type as $type ) {
1001              $rest_path = rest_get_route_for_post_type_items( $type );
1002  
1003              if ( empty( $rest_path ) ) {
1004                  continue;
1005              }
1006  
1007              $post_type_links[] = array(
1008                  'href' => add_query_arg( $this->rest_base, $term->term_id, rest_url( $rest_path ) ),
1009              );
1010          }
1011  
1012          if ( ! empty( $post_type_links ) ) {
1013              $links['https://api.w.org/post_type'] = $post_type_links;
1014          }
1015  
1016          return $links;
1017      }
1018  
1019      /**
1020       * Retrieves the term's schema, conforming to JSON Schema.
1021       *
1022       * @since 4.7.0
1023       *
1024       * @return array Item schema data.
1025       */
1026  	public function get_item_schema() {
1027          if ( $this->schema ) {
1028              return $this->add_additional_fields_schema( $this->schema );
1029          }
1030  
1031          $schema = array(
1032              '$schema'    => 'http://json-schema.org/draft-04/schema#',
1033              'title'      => 'post_tag' === $this->taxonomy ? 'tag' : $this->taxonomy,
1034              'type'       => 'object',
1035              'properties' => array(
1036                  'id'          => array(
1037                      'description' => __( 'Unique identifier for the term.' ),
1038                      'type'        => 'integer',
1039                      'context'     => array( 'view', 'embed', 'edit' ),
1040                      'readonly'    => true,
1041                  ),
1042                  'count'       => array(
1043                      'description' => __( 'Number of published posts for the term.' ),
1044                      'type'        => 'integer',
1045                      'context'     => array( 'view', 'edit' ),
1046                      'readonly'    => true,
1047                  ),
1048                  'description' => array(
1049                      'description' => __( 'HTML description of the term.' ),
1050                      'type'        => 'string',
1051                      'context'     => array( 'view', 'edit' ),
1052                  ),
1053                  'link'        => array(
1054                      'description' => __( 'URL of the term.' ),
1055                      'type'        => 'string',
1056                      'format'      => 'uri',
1057                      'context'     => array( 'view', 'embed', 'edit' ),
1058                      'readonly'    => true,
1059                  ),
1060                  'name'        => array(
1061                      'description' => __( 'HTML title for the term.' ),
1062                      'type'        => 'string',
1063                      'context'     => array( 'view', 'embed', 'edit' ),
1064                      'arg_options' => array(
1065                          'sanitize_callback' => 'sanitize_text_field',
1066                      ),
1067                      'required'    => true,
1068                  ),
1069                  'slug'        => array(
1070                      'description' => __( 'An alphanumeric identifier for the term unique to its type.' ),
1071                      'type'        => 'string',
1072                      'context'     => array( 'view', 'embed', 'edit' ),
1073                      'arg_options' => array(
1074                          'sanitize_callback' => array( $this, 'sanitize_slug' ),
1075                      ),
1076                  ),
1077                  'taxonomy'    => array(
1078                      'description' => __( 'Type attribution for the term.' ),
1079                      'type'        => 'string',
1080                      'enum'        => array( $this->taxonomy ),
1081                      'context'     => array( 'view', 'embed', 'edit' ),
1082                      'readonly'    => true,
1083                  ),
1084              ),
1085          );
1086  
1087          $taxonomy = get_taxonomy( $this->taxonomy );
1088  
1089          if ( $taxonomy->hierarchical ) {
1090              $schema['properties']['parent'] = array(
1091                  'description' => __( 'The parent term ID.' ),
1092                  'type'        => 'integer',
1093                  'context'     => array( 'view', 'edit' ),
1094              );
1095          }
1096  
1097          $schema['properties']['meta'] = $this->meta->get_field_schema();
1098  
1099          $this->schema = $schema;
1100  
1101          return $this->add_additional_fields_schema( $this->schema );
1102      }
1103  
1104      /**
1105       * Retrieves the query params for collections.
1106       *
1107       * @since 4.7.0
1108       *
1109       * @return array Collection parameters.
1110       */
1111  	public function get_collection_params() {
1112          $query_params = parent::get_collection_params();
1113          $taxonomy     = get_taxonomy( $this->taxonomy );
1114  
1115          $query_params['context']['default'] = 'view';
1116  
1117          $query_params['exclude'] = array(
1118              'description' => __( 'Ensure result set excludes specific IDs.' ),
1119              'type'        => 'array',
1120              'items'       => array(
1121                  'type' => 'integer',
1122              ),
1123              'default'     => array(),
1124          );
1125  
1126          $query_params['include'] = array(
1127              'description' => __( 'Limit result set to specific IDs.' ),
1128              'type'        => 'array',
1129              'items'       => array(
1130                  'type' => 'integer',
1131              ),
1132              'default'     => array(),
1133          );
1134  
1135          if ( ! $taxonomy->hierarchical ) {
1136              $query_params['offset'] = array(
1137                  'description' => __( 'Offset the result set by a specific number of items.' ),
1138                  'type'        => 'integer',
1139              );
1140          }
1141  
1142          $query_params['order'] = array(
1143              'description' => __( 'Order sort attribute ascending or descending.' ),
1144              'type'        => 'string',
1145              'default'     => 'asc',
1146              'enum'        => array(
1147                  'asc',
1148                  'desc',
1149              ),
1150          );
1151  
1152          $query_params['orderby'] = array(
1153              'description' => __( 'Sort collection by term attribute.' ),
1154              'type'        => 'string',
1155              'default'     => 'name',
1156              'enum'        => array(
1157                  'id',
1158                  'include',
1159                  'name',
1160                  'slug',
1161                  'include_slugs',
1162                  'term_group',
1163                  'description',
1164                  'count',
1165              ),
1166          );
1167  
1168          $query_params['hide_empty'] = array(
1169              'description' => __( 'Whether to hide terms not assigned to any posts.' ),
1170              'type'        => 'boolean',
1171              'default'     => false,
1172          );
1173  
1174          if ( $taxonomy->hierarchical ) {
1175              $query_params['parent'] = array(
1176                  'description' => __( 'Limit result set to terms assigned to a specific parent.' ),
1177                  'type'        => 'integer',
1178              );
1179          }
1180  
1181          $query_params['post'] = array(
1182              'description' => __( 'Limit result set to terms assigned to a specific post.' ),
1183              'type'        => 'integer',
1184              'default'     => null,
1185          );
1186  
1187          $query_params['slug'] = array(
1188              'description' => __( 'Limit result set to terms with one or more specific slugs.' ),
1189              'type'        => 'array',
1190              'items'       => array(
1191                  'type' => 'string',
1192              ),
1193          );
1194  
1195          /**
1196           * Filters collection parameters for the terms controller.
1197           *
1198           * The dynamic part of the filter `$this->taxonomy` refers to the taxonomy
1199           * slug for the controller.
1200           *
1201           * This filter registers the collection parameter, but does not map the
1202           * collection parameter to an internal WP_Term_Query parameter.  Use the
1203           * `rest_{$this->taxonomy}_query` filter to set WP_Term_Query parameters.
1204           *
1205           * @since 4.7.0
1206           *
1207           * @param array       $query_params JSON Schema-formatted collection parameters.
1208           * @param WP_Taxonomy $taxonomy     Taxonomy object.
1209           */
1210          return apply_filters( "rest_{$this->taxonomy}_collection_params", $query_params, $taxonomy );
1211      }
1212  
1213      /**
1214       * Checks that the taxonomy is valid.
1215       *
1216       * @since 4.7.0
1217       *
1218       * @param string $taxonomy Taxonomy to check.
1219       * @return bool Whether the taxonomy is allowed for REST management.
1220       */
1221  	protected function check_is_taxonomy_allowed( $taxonomy ) {
1222          $taxonomy_obj = get_taxonomy( $taxonomy );
1223          if ( $taxonomy_obj && ! empty( $taxonomy_obj->show_in_rest ) ) {
1224              return true;
1225          }
1226          return false;
1227      }
1228  }


Generated : Tue Dec 24 08:20:01 2024 Cross-referenced by PHPXref