WordPress.org
Get WordPress

Make WordPress Core

Changeset 39033


Ignore:
Timestamp:
10/30/2016 06:20:58 PM (8 years ago)
Author:
DrewAPicture
Message:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Terms_Controller class.

Props Soean, mrahmadawais, flixos90.
See #38398.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php

    r38974 r39033  
    11<?php
    2 
    32/**
    4  * Access terms associated with a taxonomy.
     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
    516 */
    617class WP_REST_Terms_Controller extends WP_REST_Controller {
    … …  
    920     * Taxonomy key.
    1021     *
     22     * @since 4.7.0
    1123     * @access protected
    1224     * @var string
    … …  
    1729     * Instance of a term meta fields object.
    1830     *
     31     * @since 4.7.0
    1932     * @access protected
    2033     * @var WP_REST_Term_Meta_Fields
    … …  
    2538     * Column to have the terms be sorted by.
    2639     *
     40     * @since 4.7.0
    2741     * @access protected
    2842     * @var string
    … …  
    3347     * Number of terms that were found.
    3448     *
     49     * @since 4.7.0
    3550     * @access protected
    3651     * @var int
    … …  
    4055    /**
    4156     * Constructor.
     57     *
     58     * @since 4.7.0
     59     * @access public
    4260     *
    4361     * @param string $taxonomy Taxonomy key.
    … …  
    5472    /**
    5573     * Registers the routes for the objects of the controller.
     74     *
     75     * @since 4.7.0
     76     * @access public
     77     *
     78     * @see register_rest_route()
    5679     */
    5780    public function register_routes() {
    … …  
    7295            'schema' => array( $this, 'get_public_item_schema' ),
    7396        ) );
     97
    7498        register_rest_route( $this->namespace, '/' . $this->rest_base . '/(?P<id>[\d]+)', array(
    7599            array(
    … …  
    105129     * Checks if a request has access to read terms in the specified taxonomy.
    106130     *
    107      * @param  WP_REST_Request $request Full details about the request.
    108      * @return WP_Error|boolean
     131     * @since 4.7.0
     132     * @access public
     133     *
     134     * @param WP_REST_Request $request Full details about the request.
     135     * @return bool|WP_Error True if the request has read access, otherwise false or WP_Error object.
    109136     */
    110137    public function get_items_permissions_check( $request ) {
    … …  
    120147
    121148    /**
    122      * Gets terms associated with a taxonomy.
     149     * Retrieves terms associated with a taxonomy.
     150     *
     151     * @since 4.7.0
     152     * @access public
    123153     *
    124154     * @param WP_REST_Request $request Full details about the request.
    125      * @return WP_REST_Response|WP_Error
     155     * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
    126156     */
    127157    public function get_items( $request ) {
    … …  
    130160        $registered = $this->get_collection_params();
    131161
    132         // This array defines mappings between public API query parameters whose
    133         // values are accepted as-passed, and their internal WP_Query parameter
    134         // name equivalents (some are the same). Only values which are also
    135         // present in $registered will be set.
     162        /*
     163         * This array defines mappings between public API query parameters whose
     164         * values are accepted as-passed, and their internal WP_Query parameter
     165         * name equivalents (some are the same). Only values which are also
     166         * present in $registered will be set.
     167         */
    136168        $parameter_mappings = array(
    137169            'exclude'    => 'exclude',
    … …  
    148180        $prepared_args = array();
    149181
    150         // For each known parameter which is both registered and present in the request,
    151         // set the parameter's value on the query $prepared_args.
     182        /*
     183         * For each known parameter which is both registered and present in the request,
     184         * set the parameter's value on the query $prepared_args.
     185         */
    152186        foreach ( $parameter_mappings as $api_param => $wp_param ) {
    153187            if ( isset( $registered[ $api_param ], $request[ $api_param ] ) ) {
    … …  
    178212         * Filters the query arguments before passing them to get_terms().
    179213         *
     214         * The dynamic portion of the hook name, `$this->taxonomy`, refers to the taxonomy slug.
     215         *
    180216         * Enables adding extra arguments or setting defaults for a terms
    181217         * collection request.
    182218         *
    183          * @see https://developer.wordpress.org/reference/functions/get_terms/
     219         * @since 4.7.0
     220         *
     221         * @link https://developer.wordpress.org/reference/functions/get_terms/
    184222         *
    185223         * @param array           $prepared_args Array of arguments to be
    … …  
    199237
    200238        $count_args = $prepared_args;
     239
    201240        unset( $count_args['number'], $count_args['offset'] );
     241
    202242        $total_terms = wp_count_terms( $this->taxonomy, $count_args );
    203243
    204         // wp_count_terms can return a falsy value when the term has no children
     244        // wp_count_terms can return a falsy value when the term has no children.
    205245        if ( ! $total_terms ) {
    206246            $total_terms = 0;
    … …  
    208248
    209249        $response = array();
     250
    210251        foreach ( $query_result as $term ) {
    211252            $data = $this->prepare_item_for_response( $term, $request );
    … …  
    217258        // Store pagination values for headers.
    218259        $per_page = (int) $prepared_args['number'];
    219         $page = ceil( ( ( (int) $prepared_args['offset'] ) / $per_page ) + 1 );
     260        $page     = ceil( ( ( (int) $prepared_args['offset'] ) / $per_page ) + 1 );
    220261
    221262        $response->header( 'X-WP-Total', (int) $total_terms );
     263
    222264        $max_pages = ceil( $total_terms / $per_page );
     265
    223266        $response->header( 'X-WP-TotalPages', (int) $max_pages );
    224267
    … …  
    226269        if ( $page > 1 ) {
    227270            $prev_page = $page - 1;
     271
    228272            if ( $prev_page > $max_pages ) {
    229273                $prev_page = $max_pages;
    230274            }
     275
    231276            $prev_link = add_query_arg( 'page', $prev_page, $base );
    232277            $response->link_header( 'prev', $prev_link );
    … …  
    235280            $next_page = $page + 1;
    236281            $next_link = add_query_arg( 'page', $next_page, $base );
     282
    237283            $response->link_header( 'next', $next_link );
    238284        }
    … …  
    244290     * Checks if a request has access to read the specified term.
    245291     *
    246      * @param  WP_REST_Request $request Full details about the request.
    247      * @return WP_Error|boolean
     292     * @since 4.7.0
     293     * @access public
     294     *
     295     * @param WP_REST_Request $request Full details about the request.
     296     * @return bool|WP_Error True if the request has read access for the item, otherwise false or WP_Error object.
    248297     */
    249298    public function get_item_permissions_check( $request ) {
    … …  
    261310     * Gets a single term from a taxonomy.
    262311     *
    263      * @param WP_REST_Request $request Full details about the request
    264      * @return WP_REST_Request|WP_Error
     312     * @since 4.7.0
     313     * @access public
     314     *
     315     * @param WP_REST_Request $request Full details about the request.
     316     * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
    265317     */
    266318    public function get_item( $request ) {
    267319
    268320        $term = get_term( (int) $request['id'], $this->taxonomy );
     321
    269322        if ( ! $term || $term->taxonomy !== $this->taxonomy ) {
    270323            return new WP_Error( 'rest_term_invalid', __( "Resource doesn't exist." ), array( 'status' => 404 ) );
    271324        }
     325
    272326        if ( is_wp_error( $term ) ) {
    273327            return $term;
    … …  
    282336     * Checks if a request has access to create a term.
    283337     *
    284      * @param  WP_REST_Request $request Full details about the request.
    285      * @return WP_Error|boolean
     338     * @since 4.7.0
     339     * @access public
     340     *
     341     * @param WP_REST_Request $request Full details about the request.
     342     * @return bool|WP_Error True if the request has access to create items, false or WP_Error object otherwise.
    286343     */
    287344    public function create_item_permissions_check( $request ) {
    … …  
    302359     * Creates a single term in a taxonomy.
    303360     *
    304      * @param WP_REST_Request $request Full details about the request
    305      * @return WP_REST_Request|WP_Error
     361     * @since 4.7.0
     362     * @access public
     363     *
     364     * @param WP_REST_Request $request Full details about the request.
     365     * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
    306366     */
    307367    public function create_item( $request ) {
    … …  
    322382        $term = wp_insert_term( $prepared_term->name, $this->taxonomy, $prepared_term );
    323383        if ( is_wp_error( $term ) ) {
    324 
    325384            /*
    326385             * If we're going to inform the client that the term already exists,
    … …  
    340399         * Fires after a single term is created or updated via the REST API.
    341400         *
     401         * The dynamic portion of the hook name, `$this->taxonomy`, refers to the taxonomy slug.
     402         *
     403         * @since 4.7.0
     404         *
    342405         * @param WP_Term         $term     Inserted Term object.
    343406         * @param WP_REST_Request $request  Request object.
    344          * @param boolean         $creating True when creating term, false when updating.
     407         * @param bool            $creating True when creating term, false when updating.
    345408         */
    346409        do_action( "rest_insert_{$this->taxonomy}", $term, $request, true );
    … …  
    349412        if ( ! empty( $schema['properties']['meta'] ) && isset( $request['meta'] ) ) {
    350413            $meta_update = $this->meta->update_value( $request['meta'], (int) $request['id'] );
     414
    351415            if ( is_wp_error( $meta_update ) ) {
    352416                return $meta_update;
    … …  
    355419
    356420        $fields_update = $this->update_additional_fields_for_object( $term, $request );
     421
    357422        if ( is_wp_error( $fields_update ) ) {
    358423            return $fields_update;
    … …  
    360425
    361426        $request->set_param( 'context', 'view' );
     427
    362428        $response = $this->prepare_item_for_response( $term, $request );
    363429        $response = rest_ensure_response( $response );
     430
    364431        $response->set_status( 201 );
    365432        $response->header( 'Location', rest_url( $this->namespace . '/' . $this->rest_base . '/' . $term->term_id ) );
     433
    366434        return $response;
    367435    }
    … …  
    370438     * Checks if a request has access to update the specified term.
    371439     *
    372      * @param  WP_REST_Request $request Full details about the request.
    373      * @return WP_Error|boolean
     440     * @since 4.7.0
     441     * @access public
     442     *
     443     * @param WP_REST_Request $request Full details about the request.
     444     * @return bool|WP_Error True if the request has access to update the item, false or WP_Error object otherwise.
    374445     */
    375446    public function update_item_permissions_check( $request ) {
    … …  
    380451
    381452        $term = get_term( (int) $request['id'], $this->taxonomy );
     453
    382454        if ( ! $term ) {
    383455            return new WP_Error( 'rest_term_invalid', __( "Resource doesn't exist." ), array( 'status' => 404 ) );
    … …  
    394466     * Updates a single term from a taxonomy.
    395467     *
    396      * @param WP_REST_Request $request Full details about the request
    397      * @return WP_REST_Request|WP_Error
     468     * @since 4.7.0
     469     * @access public
     470     *
     471     * @param WP_REST_Request $request Full details about the request.
     472     * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
    398473     */
    399474    public function update_item( $request ) {
    … …  
    417492        if ( ! empty( $prepared_term ) ) {
    418493            $update = wp_update_term( $term->term_id, $term->taxonomy, (array) $prepared_term );
     494
    419495            if ( is_wp_error( $update ) ) {
    420496                return $update;
    … …  
    430506        if ( ! empty( $schema['properties']['meta'] ) && isset( $request['meta'] ) ) {
    431507            $meta_update = $this->meta->update_value( $request['meta'], (int) $request['id'] );
     508
    432509            if ( is_wp_error( $meta_update ) ) {
    433510                return $meta_update;
    … …  
    436513
    437514        $fields_update = $this->update_additional_fields_for_object( $term, $request );
     515
    438516        if ( is_wp_error( $fields_update ) ) {
    439517            return $fields_update;
    … …  
    441519
    442520        $request->set_param( 'context', 'view' );
     521
    443522        $response = $this->prepare_item_for_response( $term, $request );
     523
    444524        return rest_ensure_response( $response );
    445525    }
    … …  
    448528     * Checks if a request has access to delete the specified term.
    449529     *
    450      * @param  WP_REST_Request $request Full details about the request.
    451      * @return WP_Error|boolean
     530     * @since 4.7.0
     531     * @access public
     532     *
     533     * @param WP_REST_Request $request Full details about the request.
     534     * @return bool|WP_Error True if the request has access to delete the item, otherwise false or WP_Error object.
    452535     */
    453536    public function delete_item_permissions_check( $request ) {
    … …  
    455538            return false;
    456539        }
     540
    457541        $term = get_term( (int) $request['id'], $this->taxonomy );
     542
    458543        if ( ! $term ) {
    459544            return new WP_Error( 'rest_term_invalid', __( "Resource doesn't exist." ), array( 'status' => 404 ) );
    … …  
    463548            return new WP_Error( 'rest_cannot_delete', __( 'Sorry, you cannot delete resource.' ), array( 'status' => rest_authorization_required_code() ) );
    464549        }
     550
    465551        return true;
    466552    }
    … …  
    469555     * Deletes a single term from a taxonomy.
    470556     *
    471      * @param WP_REST_Request $request Full details about the request
    472      * @return WP_REST_Response|WP_Error
     557     * @since 4.7.0
     558     * @access public
     559     *
     560     * @param WP_REST_Request $request Full details about the request.
     561     * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
    473562     */
    474563    public function delete_item( $request ) {
    … …  
    482571
    483572        $term = get_term( (int) $request['id'], $this->taxonomy );
     573
    484574        $request->set_param( 'context', 'view' );
     575
    485576        $response = $this->prepare_item_for_response( $term, $request );
    486577
    487578        $retval = wp_delete_term( $term->term_id, $term->taxonomy );
     579
    488580        if ( ! $retval ) {
    489581            return new WP_Error( 'rest_cannot_delete', __( 'The resource cannot be deleted.' ), array( 'status' => 500 ) );
    … …  
    492584        /**
    493585         * Fires after a single term is deleted via the REST API.
     586         *
     587         * The dynamic portion of the hook name, `$this->taxonomy`, refers to the taxonomy slug.
     588         *
     589         * @since 4.7.0
    494590         *
    495591         * @param WP_Term          $term     The deleted term.
    … …  
    505601     * Prepares a single term for create or update.
    506602     *
     603     * @since 4.7.0
     604     * @access public
     605     *
    507606     * @param WP_REST_Request $request Request object.
    508607     * @return object $prepared_term Term object.
    … …  
    530629        if ( isset( $request['parent'] ) && ! empty( $schema['properties']['parent'] ) ) {
    531630            $parent_term_id = 0;
    532             $parent_term = get_term( (int) $request['parent'], $this->taxonomy );
     631            $parent_term    = get_term( (int) $request['parent'], $this->taxonomy );
    533632
    534633            if ( $parent_term ) {
    … …  
    541640        /**
    542641         * Filters term data before inserting term via the REST API.
     642         *
     643         * The dynamic portion of the hook name, `$this->taxonomy`, refers to the taxonomy slug.
     644         *
     645         * @since 4.7.0
    543646         *
    544647         * @param object          $prepared_term Term object.
    … …  
    551654     * Prepares a single term output for response.
    552655     *
     656     * @since 4.7.0
     657     * @access public
     658     *
    553659     * @param obj             $item    Term object.
    554660     * @param WP_REST_Request $request Request object.
    555      * @return WP_REST_Response $response
     661     * @return WP_REST_Response $response Response object.
    556662     */
    557663    public function prepare_item_for_response( $item, $request ) {
    558664
    559665        $schema = $this->get_item_schema();
    560         $data = array();
     666        $data   = array();
     667
    561668        if ( ! empty( $schema['properties']['id'] ) ) {
    562669            $data['id'] = (int) $item->term_id;
    563670        }
     671
    564672        if ( ! empty( $schema['properties']['count'] ) ) {
    565673            $data['count'] = (int) $item->count;
    566674        }
     675
    567676        if ( ! empty( $schema['properties']['description'] ) ) {
    568677            $data['description'] = $item->description;
    569678        }
     679
    570680        if ( ! empty( $schema['properties']['link'] ) ) {
    571681            $data['link'] = get_term_link( $item );
    572682        }
     683
    573684        if ( ! empty( $schema['properties']['name'] ) ) {
    574685            $data['name'] = $item->name;
    575686        }
     687
    576688        if ( ! empty( $schema['properties']['slug'] ) ) {
    577689            $data['slug'] = $item->slug;
    578690        }
     691
    579692        if ( ! empty( $schema['properties']['taxonomy'] ) ) {
    580693            $data['taxonomy'] = $item->taxonomy;
    581694        }
     695
    582696        if ( ! empty( $schema['properties']['parent'] ) ) {
    583697            $data['parent'] = (int) $item->parent;
    584698        }
     699
    585700        if ( ! empty( $schema['properties']['meta'] ) ) {
    586701            $data['meta'] = $this->meta->get_value( $item->term_id, $request );
    … …  
    588703
    589704        $context = ! empty( $request['context'] ) ? $request['context'] : 'view';
    590         $data = $this->add_additional_fields_to_object( $data, $request );
    591         $data = $this->filter_response_by_context( $data, $context );
     705        $data    = $this->add_additional_fields_to_object( $data, $request );
     706        $data    = $this->filter_response_by_context( $data, $context );
    592707
    593708        $response = rest_ensure_response( $data );
    … …  
    598713         * Filters a term item returned from the API.
    599714         *
     715         * The dynamic portion of the hook name, `$this->taxonomy`, refers to the taxonomy slug.
     716         *
    600717         * Allows modification of the term data right before it is returned.
     718         *
     719         * @since 4.7.0
    601720         *
    602721         * @param WP_REST_Response  $response  The response object.
    … …  
    610729     * Prepares links for the request.
    611730     *
     731     * @since 4.7.0
     732     * @access protected
     733     *
    612734     * @param object $term Term object.
    613735     * @return array Links for the given term.
    … …  
    629751        if ( $term->parent ) {
    630752            $parent_term = get_term( (int) $term->parent, $term->taxonomy );
     753
    631754            if ( $parent_term ) {
    632755                $links['up'] = array(
    … …  
    638761
    639762        $taxonomy_obj = get_taxonomy( $term->taxonomy );
     763
    640764        if ( empty( $taxonomy_obj->object_type ) ) {
    641765            return $links;
    … …  
    643767
    644768        $post_type_links = array();
     769
    645770        foreach ( $taxonomy_obj->object_type as $type ) {
    646771            $post_type_object = get_post_type_object( $type );
     772
    647773            if ( empty( $post_type_object->show_in_rest ) ) {
    648774                continue;
    649775            }
     776
    650777            $rest_base = ! empty( $post_type_object->rest_base ) ? $post_type_object->rest_base : $post_type_object->name;
    651778            $post_type_links[] = array(
    … …  
    653780            );
    654781        }
     782
    655783        if ( ! empty( $post_type_links ) ) {
    656784            $links['https://api.w.org/post_type'] = $post_type_links;
    … …  
    661789
    662790    /**
    663      * Gets the term's schema, conforming to JSON Schema.
    664      *
    665      * @return array
     791     * Retrieves the term's schema, conforming to JSON Schema.
     792     *
     793     * @since 4.7.0
     794     * @access public
     795     *
     796     * @return array Item schema data.
    666797     */
    667798    public function get_item_schema() {
    … …  
    724855            ),
    725856        );
     857
    726858        $taxonomy = get_taxonomy( $this->taxonomy );
     859
    727860        if ( $taxonomy->hierarchical ) {
    728861            $schema['properties']['parent'] = array(
    … …  
    734867
    735868        $schema['properties']['meta'] = $this->meta->get_field_schema();
     869
    736870        return $this->add_additional_fields_schema( $schema );
    737871    }
    738872
    739873    /**
    740      * Gets the query params for collections.
    741      *
    742      * @return array
     874     * Retrieves the query params for collections.
     875     *
     876     * @since 4.7.0
     877     * @access public
     878     *
     879     * @return array Collection parameters.
    743880     */
    744881    public function get_collection_params() {
    … …  
    754891            'sanitize_callback' => 'wp_parse_id_list',
    755892        );
     893
    756894        $query_params['include'] = array(
    757895            'description'       => __( 'Limit result set to specific ids.' ),
    … …  
    760898            'sanitize_callback' => 'wp_parse_id_list',
    761899        );
     900
    762901        if ( ! $taxonomy->hierarchical ) {
    763902            $query_params['offset'] = array(
    … …  
    768907            );
    769908        }
     909
    770910        $query_params['order'] = array(
    771911            'description'       => __( 'Order sort attribute ascending or descending.' ),
    … …  
    779919            'validate_callback' => 'rest_validate_request_arg',
    780920        );
     921
    781922        $query_params['orderby'] = array(
    782923            'description'       => __( 'Sort collection by resource attribute.' ),
    … …  
    795936            'validate_callback' => 'rest_validate_request_arg',
    796937        );
     938
    797939        $query_params['hide_empty'] = array(
    798940            'description'       => __( 'Whether to hide resources not assigned to any posts.' ),
    … …  
    802944            'validate_callback' => 'rest_validate_request_arg',
    803945        );
     946
    804947        if ( $taxonomy->hierarchical ) {
    805948            $query_params['parent'] = array(
    … …  
    810953            );
    811954        }
     955
    812956        $query_params['post'] = array(
    813957            'description'       => __( 'Limit result set to resources assigned to a specific post.' ),
    … …  
    816960            'validate_callback' => 'rest_validate_request_arg',
    817961        );
     962
    818963        $query_params['slug'] = array(
    819964            'description'       => __( 'Limit result set to resources with a specific slug.' ),
    … …  
    821966            'validate_callback' => 'rest_validate_request_arg',
    822967        );
     968
    823969        return $query_params;
    824970    }
    … …  
    827973     * Checks that the taxonomy is valid.
    828974     *
     975     * @since 4.7.0
     976     * @access protected
     977     *
    829978     * @param string $taxonomy Taxonomy to check.
    830      * @return WP_Error|boolean
     979     * @return bool Whether the taxonomy is allowed for REST management.
    831980     */
    832981    protected function check_is_taxonomy_allowed( $taxonomy ) {
Note: See TracChangeset for help on using the changeset viewer.