WordPress.org
Get WordPress

Make WordPress Core

Changeset 39033


Ignore:
Timestamp:
10/30/2016 06:20:58 PM (10 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.