WordPress.org

Make WordPress Core

Ticket #38398: 38398.7.patch

File 38398.7.patch, 87.5 KB (added by mrahmadawais, 4 years ago)

FIX: WP Doc & Coding standards like missing end foreach() comments, periods after inline comments, file header DocBlocks, class var DocBlocks.

  • wp-includes/rest-api/class-wp-rest-request.php

     
    359359
    360360                // Ensure we parse the body data.
    361361                $body = $this->get_body();
    362                 if ( $this->method !== 'POST' && ! empty( $body ) ) {
     362                if ( 'POST' !== $this->method && ! empty( $body ) ) {
    363363                        $this->parse_body_params();
    364364                }
    365365
     
    967967
    968968                $api_root = rest_url();
    969969                if ( get_option( 'permalink_structure' ) && 0 === strpos( $url, $api_root ) ) {
    970                         // Pretty permalinks on, and URL is under the API root
     970                        // Pretty permalinks on, and URL is under the API root.
    971971                        $api_url_part = substr( $url, strlen( untrailingslashit( $api_root ) ) );
    972972                        $route = parse_url( $api_url_part, PHP_URL_PATH );
    973973                } elseif ( ! empty( $query_params['rest_route'] ) ) {
  • wp-includes/rest-api/class-wp-rest-response.php

     
    246246                        $data = $this->get_data();
    247247                        $error->add( $data['code'], $data['message'], $data['data'] );
    248248                        if ( ! empty( $data['additional_errors'] ) ) {
    249                                 foreach( $data['additional_errors'] as $err ) {
     249                                foreach ( $data['additional_errors'] as $err ) {
    250250                                        $error->add( $err['code'], $err['message'], $err['data'] );
    251251                                }
    252252                        }
  • wp-includes/rest-api/class-wp-rest-server.php

     
    394394                        }
    395395
    396396                        if ( $jsonp_callback ) {
    397                                 // Prepend '/**/' to mitigate possible JSONP Flash attacks
     397                                // Prepend '/**/' to mitigate possible JSONP Flash attacks.
    398398                                // https://miki.it/blog/2014/7/8/abusing-jsonp-with-rosetta-flash/
    399399                                echo '/**/' . $jsonp_callback . '(' . $result . ')';
    400400                        } else {
     
    505505                                        continue;
    506506                                }
    507507
    508                                 // Relation now changes from '$uri' to '$curie:$relation'
     508                                // Relation now changes from '$uri' to '$curie:$relation'.
    509509                                $rel_regex = str_replace( '\{rel\}', '(.+)', preg_quote( $curie['href'], '!' ) );
    510510                                preg_match( '!' . $rel_regex . '!', $rel, $matches );
    511511                                if ( $matches ) {
     
    588588                        if ( $has_links ) {
    589589                                $embedded[ $rel ] = $embeds;
    590590                        }
    591                 }
     591                } // End foreach().
    592592
    593593                if ( ! empty( $embedded ) ) {
    594594                        $data['_embedded'] = $embedded;
     
    744744                                // Allow comma-separated HTTP methods.
    745745                                if ( is_string( $handler['methods'] ) ) {
    746746                                        $methods = explode( ',', $handler['methods'] );
    747                                 } else if ( is_array( $handler['methods'] ) ) {
     747                                } elseif ( is_array( $handler['methods'] ) ) {
    748748                                        $methods = $handler['methods'];
    749749                                } else {
    750750                                        $methods = array();
     
    756756                                        $method = strtoupper( trim( $method ) );
    757757                                        $handler['methods'][ $method ] = true;
    758758                                }
    759                         }
    760                 }
     759                        } // End foreach().
     760                } // End foreach().
    761761                return $endpoints;
    762762        }
    763763
     
    899899
    900900                                                if ( is_wp_error( $permission ) ) {
    901901                                                        $response = $permission;
    902                                                 } else if ( false === $permission || null === $permission ) {
     902                                                } elseif ( false === $permission || null === $permission ) {
    903903                                                        $response = new WP_Error( 'rest_forbidden', __( 'Sorry, you are not allowed to do that.' ), array( 'status' => 403 ) );
    904904                                                }
    905905                                        }
     
    961961                                $response->set_matched_handler( $handler );
    962962
    963963                                return $response;
    964                         }
    965                 }
     964                        } // End foreach().
     965                } // End foreach().
    966966
    967967                return $this->error_to_response( new WP_Error( 'rest_no_route', __( 'No route was found matching the URL and request method' ), array( 'status' => 404 ) ) );
    968968        }
     
    11961196                                        'self' => rest_url( $route ),
    11971197                                );
    11981198                        }
    1199                 }
     1199                } // End foreach().
    12001200
    12011201                if ( empty( $data['methods'] ) ) {
    12021202                        // No methods supported, hide the route.
  • wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Attachments_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
     10/**
     11 * Access attachments.
     12 *
     13 * @since 4.7.0
     14 */
    315class WP_REST_Attachments_Controller extends WP_REST_Posts_Controller {
    416
    517        /**
     
    618         * Determine the allowed query_vars for a get_items() response and
    719         * prepare for WP_Query.
    820         *
     21         * @since 4.7.0
     22         *
    923         * @param array           $prepared_args Optional. Array of prepared arguments.
    1024         * @param WP_REST_Request $request       Optional. Request to prepare items for.
    1125         * @return array Array of query arguments.
     
    3145        /**
    3246         * Check if a given request has access to create an attachment.
    3347         *
     48         * @since 4.7.0
     49         *
    3450         * @param  WP_REST_Request $request Full details about the request.
    3551         * @return WP_Error|true Boolean true if the attachment may be created, or a WP_Error if not.
    3652         */
     
    5975        /**
    6076         * Create a single attachment.
    6177         *
     78         * @since 4.7.0
     79         *
    6280         * @param WP_REST_Request $request Full details about the request.
    6381         * @return WP_Error|WP_REST_Response Response object on success, WP_Error object on failure.
    6482         */
     
    6886                        return new WP_Error( 'rest_invalid_param', __( 'Invalid parent type.' ), array( 'status' => 400 ) );
    6987                }
    7088
    71                 // Get the file via $_FILES or raw data
     89                // Get the file via $_FILES or raw data.
    7290                $files = $request->get_file_params();
    7391                $headers = $request->get_headers();
    7492                if ( ! empty( $files ) ) {
     
    146164                /**
    147165                 * Fires after a single attachment is created or updated via the REST API.
    148166                 *
     167                 * @since 4.7.0
     168                 *
    149169                 * @param object          $attachment Inserted attachment.
    150170                 * @param WP_REST_Request $request    The request sent to the API.
    151171                 * @param boolean         $creating   True when creating an attachment, false when updating.
     
    159179        /**
    160180         * Update a single post.
    161181         *
     182         * @since 4.7.0
     183         *
    162184         * @param WP_REST_Request $request Full details about the request.
    163185         * @return WP_Error|WP_REST_Response Response object on success, WP_Error object on failure.
    164186         */
     
    198220        /**
    199221         * Prepare a single attachment for create or update.
    200222         *
     223         * @since 4.7.0
     224         *
    201225         * @param WP_REST_Request $request Request object.
    202226         * @return WP_Error|stdClass $prepared_attachment Post object.
    203227         */
     
    222246        /**
    223247         * Prepare a single attachment output for response.
    224248         *
     249         * @since 4.7.0
     250         *
    225251         * @param WP_Post         $post    Post object.
    226252         * @param WP_REST_Request $request Request object.
    227253         * @return WP_REST_Response Response object.
     
    288314                 *
    289315                 * Allows modification of the attachment right before it is returned.
    290316                 *
     317                 * @since 4.7.0
     318                 *
    291319                 * @param WP_REST_Response  $response   The response object.
    292320                 * @param WP_Post           $post       The original attachment post.
    293321                 * @param WP_REST_Request   $request    Request used to generate the response.
     
    298326        /**
    299327         * Get the Attachment's schema, conforming to JSON Schema.
    300328         *
     329         * @since 4.7.0
     330         *
    301331         * @return array Item schema as an array.
    302332         */
    303333        public function get_item_schema() {
     
    365395        /**
    366396         * Handle an upload via raw POST data.
    367397         *
     398         * @since 4.7.0
     399         *
    368400         * @param array $data    Supplied file data.
    369401         * @param array $headers HTTP headers from the request.
    370402         * @return array|WP_Error Data from {@see wp_handle_sideload()}.
     
    459491         *                         | ext-token "=" ext-value
    460492         *     ext-token           = <the characters in token, followed by "*">
    461493         *
     494         * @since 4.7.0
     495         *
    462496         * @see http://tools.ietf.org/html/rfc2388
    463497         * @see http://tools.ietf.org/html/rfc6266
    464498         *
     
    506540        /**
    507541         * Get the query params for collections of attachments.
    508542         *
     543         * @since 4.7.0
     544         *
    509545         * @return array Query parameters for the attachment collection as an array.
    510546         */
    511547        public function get_collection_params() {
     
    531567        /**
    532568         * Validate whether the user can query private statuses
    533569         *
     570         * @since 4.7.0
     571         *
    534572         * @param  mixed           $value     Status value.
    535573         * @param  WP_REST_Request $request   Request object.
    536574         * @param  string          $parameter Additional parameter to pass to validation.
     
    546584        /**
    547585         * Handle an upload via multipart/form-data ($_FILES).
    548586         *
     587         * @since 4.7.0
     588         *
    549589         * @param array $files   Data from $_FILES.
    550590         * @param array $headers HTTP headers from the request.
    551591         * @return array|WP_Error Data from {@see wp_handle_upload()}.
     
    590630         *
    591631         * Media types are considered the MIME type category.
    592632         *
     633         * @since 4.7.0
     634         *
    593635         * @return array
    594636         */
    595637        protected function get_media_types() {
  • wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Comments_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
    310/**
    4  * Access comments
     11 * Access comments.
     12 *
     13 * @since 4.7.0
    514 */
    615class WP_REST_Comments_Controller extends WP_REST_Controller {
    716
     
    817        /**
    918         * Instance of a comment meta fields object.
    1019         *
     20         * @since 4.7.0
    1121         * @access protected
    1222         * @var WP_REST_Comment_Meta_Fields
    1323         */
    1424        protected $meta;
    1525
     26        /**
     27         * Constructor.
     28         *
     29         * @since 4.7.0
     30         */
    1631        public function __construct() {
    1732                $this->namespace = 'wp/v2';
    1833                $this->rest_base = 'comments';
     
    2136        }
    2237
    2338        /**
    24          * Register the routes for the objects of the controller.
     39         * Registers the routes for the objects of the controller.
     40         *
     41         * @since 4.7.0
    2542         */
    2643        public function register_routes() {
    2744
     
    7289        }
    7390
    7491        /**
    75          * Check if a given request has access to read comments
     92         * Checks if a given request has access to read comments.
    7693         *
     94         * @since 4.7.0
     95         *
    7796         * @param  WP_REST_Request $request Full details about the request.
    7897         * @return WP_Error|boolean
    7998         */
     
    119138        }
    120139
    121140        /**
    122          * Get a list of comments.
     141         * Gets a list of comments.
    123142         *
     143         * @since 4.7.0
     144         *
    124145         * @param  WP_REST_Request $request Full details about the request.
    125146         * @return WP_Error|WP_REST_Response
    126147         */
     
    190211                }
    191212
    192213                /**
    193                  * Filter arguments, before passing to WP_Comment_Query, when querying comments via the REST API.
     214                 * Filters arguments, before passing to WP_Comment_Query, when querying comments via the REST API.
    194215                 *
    195216                 * @see https://developer.wordpress.org/reference/classes/wp_comment_query/
    196217                 *
     
    215236                $total_comments = (int) $query->found_comments;
    216237                $max_pages = (int) $query->max_num_pages;
    217238                if ( $total_comments < 1 ) {
    218                         // Out-of-bounds, run the query again without LIMIT for total count
     239                        // Out-of-bounds, run the query again without LIMIT for total count.
    219240                        unset( $prepared_args['number'], $prepared_args['offset'] );
    220241                        $query = new WP_Comment_Query;
    221242                        $prepared_args['count'] = true;
     
    247268        }
    248269
    249270        /**
    250          * Check if a given request has access to read the comment
     271         * Checks if a given request has access to read the comment.
    251272         *
     273         * @since 4.7.0
     274         *
    252275         * @param  WP_REST_Request $request Full details about the request.
    253276         * @return WP_Error|boolean
    254277         */
     
    279302        }
    280303
    281304        /**
    282          * Get a comment.
     305         * Gets a comment.
    283306         *
     307         * @since 4.7.0
     308         *
    284309         * @param  WP_REST_Request $request Full details about the request.
    285310         * @return WP_Error|WP_REST_Response
    286311         */
     
    306331        }
    307332
    308333        /**
    309          * Check if a given request has access to create a comment
     334         * Checks if a given request has access to create a comment.
    310335         *
     336         * @since 4.7.0
     337         *
    311338         * @param  WP_REST_Request $request Full details about the request.
    312339         * @return WP_Error|boolean
    313340         */
     
    354381        }
    355382
    356383        /**
    357          * Create a comment.
     384         * Creates a comment.
    358385         *
     386         * @since 4.7.0
     387         *
    359388         * @param  WP_REST_Request $request Full details about the request.
    360389         * @return WP_Error|WP_REST_Response
    361390         */
     
    378407                        return new WP_Error( 'rest_comment_content_invalid', __( 'Comment content is invalid.' ), array( 'status' => 400 ) );
    379408                }
    380409
    381                 // Setting remaining values before wp_insert_comment so we can
    382                 // use wp_allow_comment().
     410                // Setting remaining values before wp_insert_comment so we can use wp_allow_comment().
    383411                if ( ! isset( $prepared_comment['comment_date_gmt'] ) ) {
    384412                        $prepared_comment['comment_date_gmt'] = current_time( 'mysql', true );
    385413                }
    386414
    387                 // Set author data if the user's logged in
     415                // Set author data if the user's logged in.
    388416                $missing_author = empty( $prepared_comment['user_id'] )
    389417                        && empty( $prepared_comment['comment_author'] )
    390418                        && empty( $prepared_comment['comment_author_email'] )
     
    398426                        $prepared_comment['comment_author_url'] = $user->user_url;
    399427                }
    400428
    401                 // Honor the discussion setting that requires a name and email address
    402                 // of the comment author.
     429                // Honor the discussion setting that requires a name and email address of the comment author.
    403430                if ( get_option( 'require_name_email' ) ) {
    404431                        if ( ! isset( $prepared_comment['comment_author'] ) && ! isset( $prepared_comment['comment_author_email'] ) ) {
    405432                                return new WP_Error( 'rest_comment_author_data_required', __( 'Creating a comment requires valid author name and email values.' ), array( 'status' => 400 ) );
     
    445472                 *
    446473                 * Allows modification of the comment right before it is inserted via `wp_insert_comment`.
    447474                 *
     475                 * @since 4.7.0
     476                 *
    448477                 * @param array           $prepared_comment The prepared comment data for `wp_insert_comment`.
    449478                 * @param WP_REST_Request $request          Request used to insert the comment.
    450479                 */
     
    484513                /**
    485514                 * Fires after a comment is created or updated via the REST API.
    486515                 *
     516                 * @since 4.7.0
     517                 *
    487518                 * @param array           $comment  Comment as it exists in the database.
    488519                 * @param WP_REST_Request $request  The request sent to the API.
    489520                 * @param boolean         $creating True when creating a comment, false when updating.
     
    494525        }
    495526
    496527        /**
    497          * Check if a given request has access to update a comment
     528         * Checks if a given request has access to update a comment.
    498529         *
     530         * @since 4.7.0
     531         *
    499532         * @param  WP_REST_Request $request Full details about the request.
    500533         * @return WP_Error|boolean
    501534         */
     
    513546        }
    514547
    515548        /**
    516          * Edit a comment
     549         * Edits a comment.
    517550         *
     551         * @since 4.7.0
     552         *
    518553         * @param  WP_REST_Request $request Full details about the request.
    519554         * @return WP_Error|WP_REST_Response
    520555         */
     
    582617        }
    583618
    584619        /**
    585          * Check if a given request has access to delete a comment
     620         * Checks if a given request has access to delete a comment.
    586621         *
     622         * @since 4.7.0
     623         *
    587624         * @param  WP_REST_Request $request Full details about the request.
    588625         * @return WP_Error|boolean
    589626         */
     
    600637        }
    601638
    602639        /**
    603          * Delete a comment.
     640         * Deletes a comment.
    604641         *
     642         * @since 4.7.0
     643         *
    605644         * @param  WP_REST_Request $request Full details about the request.
    606645         * @return WP_Error|WP_REST_Response
    607646         */
     
    630669                if ( $force ) {
    631670                        $result = wp_delete_comment( $comment->comment_ID, true );
    632671                } else {
    633                         // If we don't support trashing for this type, error out
     672                        // If we don't support trashing for this type, error out.
    634673                        if ( ! $supports_trash ) {
    635674                                return new WP_Error( 'rest_trash_not_supported', __( 'The comment does not support trashing.' ), array( 'status' => 501 ) );
    636675                        }
     
    649688                /**
    650689                 * Fires after a comment is deleted via the REST API.
    651690                 *
     691                 * @since 4.7.0
     692                 *
    652693                 * @param object           $comment  The deleted comment data.
    653694                 * @param WP_REST_Response $response The response returned from the API.
    654695                 * @param WP_REST_Request  $request  The request sent to the API.
     
    659700        }
    660701
    661702        /**
    662          * Prepare a single comment output for response.
     703         * Prepares a single comment output for response.
    663704         *
     705         * @since 4.7.0
     706         *
    664707         * @param  object          $comment Comment object.
    665708         * @param  WP_REST_Request $request Request object.
    666709         * @return WP_REST_Response $response
     
    702745                $data = $this->add_additional_fields_to_object( $data, $request );
    703746                $data = $this->filter_response_by_context( $data, $context );
    704747
    705                 // Wrap the data in a response object
     748                // Wrap the data in a response object.
    706749                $response = rest_ensure_response( $data );
    707750
    708751                $response->add_links( $this->prepare_links( $comment ) );
    709752
    710753                /**
    711                  * Filter a comment returned from the API.
     754                 * Filters a comment returned from the API.
    712755                 *
    713756                 * Allows modification of the comment right before it is returned.
    714757                 *
     758                 * @since 4.7.0
     759                 *
    715760                 * @param WP_REST_Response  $response   The response object.
    716761                 * @param object            $comment    The original comment object.
    717762                 * @param WP_REST_Request   $request    Request used to generate the response.
     
    720765        }
    721766
    722767        /**
    723          * Prepare links for the request.
     768         * Prepares links for the request.
    724769         *
     770         * @since 4.7.0
     771         *
    725772         * @param object $comment Comment object.
    726773         * @return array Links for the given comment.
    727774         */
     
    778825        }
    779826
    780827        /**
    781          * Prepend internal property prefix to query parameters to match our response fields.
     828         * Prepends internal property prefix to query parameters to match our response fields.
    782829         *
    783          * @param  string $query_param
     830         * @since 4.7.0
     831         *
     832         * @param  string $query_param Query parameter.
    784833         * @return string $normalized
    785834         */
    786835        protected function normalize_query_param( $query_param ) {
     
    808857        }
    809858
    810859        /**
    811          * Check comment_approved to set comment status for single comment output.
     860         * Checks comment_approved to set comment status for single comment output.
    812861         *
    813          * @param  string|int $comment_approved
     862         * @since 4.7.0
     863         *
     864         * @param  string|int $comment_approved comment status.
    814865         * @return string     $status
    815866         */
    816867        protected function prepare_status_response( $comment_approved ) {
     
    837888        }
    838889
    839890        /**
    840          * Prepare a single comment to be inserted into the database.
     891         * Prepares a single comment to be inserted into the database.
    841892         *
     893         * @since 4.7.0
     894         *
    842895         * @param  WP_REST_Request $request Request object.
    843896         * @return array|WP_Error  $prepared_comment
    844897         */
     
    928981        }
    929982
    930983        /**
    931          * Get the Comment's schema, conforming to JSON Schema
     984         * Gets the Comment's schema, conforming to JSON Schema.
    932985         *
     986         * @since 4.7.0
     987         *
    933988         * @return array
    934989         */
    935990        public function get_item_schema() {
     
    10911146        }
    10921147
    10931148        /**
    1094          * Get the query params for collections
     1149         * Gets the query params for collections.
    10951150         *
     1151         * @since 4.7.0
     1152         *
    10961153         * @return array
    10971154         */
    10981155        public function get_collection_params() {
     
    12171274        }
    12181275
    12191276        /**
    1220          * Set the comment_status of a given comment object when creating or updating a comment.
     1277         * Sets the comment_status of a given comment object when creating or updating a comment.
    12211278         *
    1222          * @param string|int $new_status
    1223          * @param object     $comment
     1279         * @since 4.7.0
     1280         *
     1281         * @param string|int $new_status New comment status.
     1282         * @param object     $comment    Comment data.
    12241283         * @return boolean   $changed
    12251284         */
    12261285        protected function handle_status_param( $new_status, $comment ) {
     
    12611320        }
    12621321
    12631322        /**
    1264          * Check if we can read a post.
     1323         * Checks if we can read a post.
    12651324         *
    12661325         * Correctly handles posts with the inherit status.
    12671326         *
     1327         * @since 4.7.0
     1328         *
    12681329         * @param  WP_Post $post Post Object.
    12691330         * @return boolean Can we read it?
    12701331         */
     
    12751336        }
    12761337
    12771338        /**
    1278          * Check if we can read a comment.
     1339         * Checks if we can read a comment.
    12791340         *
    1280          * @param  object  $comment Comment object.
     1341         * @since 4.7.0
     1342         *
     1343         * @param  object $comment Comment object.
    12811344         * @return boolean Can we read it?
    12821345         */
    12831346        protected function check_read_permission( $comment ) {
     
    13061369        }
    13071370
    13081371        /**
    1309          * Check if we can edit or delete a comment.
     1372         * Checks if we can edit or delete a comment.
    13101373         *
    1311          * @param  object  $comment Comment object.
     1374         * @since 4.7.0
     1375         *
     1376         * @param  object $comment Comment object.
    13121377         * @return boolean Can we edit or delete it?
    13131378         */
    13141379        protected function check_edit_permission( $comment ) {
  • wp-includes/rest-api/endpoints/class-wp-rest-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
    3 
     10/**
     11 * Core base class extended to access via REST API.
     12 *
     13 * @since 4.7.0
     14 */
    415abstract class WP_REST_Controller {
    516
    617        /**
    718         * The namespace of this controller's route.
    819         *
     20         * @since 4.7.0
     21         * @access protected
    922         * @var string
    1023         */
    1124        protected $namespace;
     
    1326        /**
    1427         * The base of this controller's route.
    1528         *
     29         * @since 4.7.0
     30         * @access protected
    1631         * @var string
    1732         */
    1833        protected $rest_base;
    1934
    2035        /**
    21          * Register the routes for the objects of the controller.
     36         * Registers the routes for the objects of the controller.
     37         *
     38         * @since 4.7.0
    2239         */
    2340        public function register_routes() {
    2441                _doing_it_wrong( 'WP_REST_Controller::register_routes', __( 'The register_routes() method must be overridden' ), 'WPAPI-2.0' );
     
    2542        }
    2643
    2744        /**
    28          * Check if a given request has access to get items.
     45         * Checks if a given request has access to get items.
    2946         *
     47         * @since 4.7.0
     48         *
    3049         * @param WP_REST_Request $request Full data about the request.
    3150         * @return WP_Error|boolean
    3251         */
     
    3554        }
    3655
    3756        /**
    38          * Get a collection of items.
     57         * Gets a collection of items.
    3958         *
     59         * @since 4.7.0
     60         *
    4061         * @param WP_REST_Request $request Full data about the request.
    4162         * @return WP_Error|WP_REST_Response
    4263         */
     
    4566        }
    4667
    4768        /**
    48          * Check if a given request has access to get a specific item.
     69         * Checks if a given request has access to get a specific item.
    4970         *
     71         * @since 4.7.0
     72         *
    5073         * @param WP_REST_Request $request Full data about the request.
    5174         * @return WP_Error|boolean
    5275         */
     
    5578        }
    5679
    5780        /**
    58          * Get one item from the collection.
     81         * Gets one item from the collection.
    5982         *
     83         * @since 4.7.0
     84         *
    6085         * @param WP_REST_Request $request Full data about the request.
    6186         * @return WP_Error|WP_REST_Response
    6287         */
     
    6590        }
    6691
    6792        /**
    68          * Check if a given request has access to create items.
     93         * Checks if a given request has access to create items.
    6994         *
     95         * @since 4.7.0
     96         *
    7097         * @param WP_REST_Request $request Full data about the request.
    7198         * @return WP_Error|boolean
    7299         */
     
    75102        }
    76103
    77104        /**
    78          * Create one item from the collection.
     105         * Creates one item from the collection.
    79106         *
     107         * @since 4.7.0
     108         *
    80109         * @param WP_REST_Request $request Full data about the request.
    81110         * @return WP_Error|WP_REST_Response
    82111         */
     
    85114        }
    86115
    87116        /**
    88          * Check if a given request has access to update a specific item.
     117         * Checks if a given request has access to update a specific item.
    89118         *
     119         * @since 4.7.0
     120         *
    90121         * @param WP_REST_Request $request Full data about the request.
    91122         * @return WP_Error|boolean
    92123         */
     
    95126        }
    96127
    97128        /**
    98          * Update one item from the collection.
     129         * Updates one item from the collection.
    99130         *
     131         * @since 4.7.0
     132         *
    100133         * @param WP_REST_Request $request Full data about the request.
    101134         * @return WP_Error|WP_REST_Response
    102135         */
     
    105138        }
    106139
    107140        /**
    108          * Check if a given request has access to delete a specific item.
     141         * Checks if a given request has access to delete a specific item.
    109142         *
     143         * @since 4.7.0
     144         *
    110145         * @param WP_REST_Request $request Full data about the request.
    111146         * @return WP_Error|boolean
    112147         */
     
    115150        }
    116151
    117152        /**
    118          * Delete one item from the collection.
     153         * Deletes one item from the collection.
    119154         *
     155         * @since 4.7.0
     156         *
    120157         * @param WP_REST_Request $request Full data about the request.
    121158         * @return WP_Error|WP_REST_Response
    122159         */
     
    125162        }
    126163
    127164        /**
    128          * Prepare the item for create or update operation.
     165         * Prepares the item for create or update operation.
    129166         *
     167         * @since 4.7.0
     168         *
    130169         * @param WP_REST_Request $request Request object.
    131170         * @return WP_Error|object $prepared_item
    132171         */
     
    135174        }
    136175
    137176        /**
    138          * Prepare the item for the REST response.
     177         * Prepares the item for the REST response.
    139178         *
    140          * @param mixed $item WordPress representation of the item.
     179         * @since 4.7.0
     180         *
     181         * @param mixed           $item    WordPress representation of the item.
    141182         * @param WP_REST_Request $request Request object.
    142183         * @return WP_Error|WP_REST_Response $response
    143184         */
     
    146187        }
    147188
    148189        /**
    149          * Prepare a response for inserting into a collection.
     190         * Prepares a response for inserting into a collection.
    150191         *
     192         * @since 4.7.0
     193         *
    151194         * @param WP_REST_Response $response Response object.
    152195         * @return array Response data, ready for insertion into collection data.
    153196         */
     
    173216        }
    174217
    175218        /**
    176          * Filter a response based on the context defined in the schema.
     219         * Filters a response based on the context defined in the schema.
    177220         *
    178          * @param array $data
    179          * @param string $context
     221         * @since 4.7.0
     222         *
     223         * @param array  $data    Response data to fiter.
     224         * @param string $context Context defined in the schema.
    180225         * @return array
    181226         */
    182227        public function filter_response_by_context( $data, $context ) {
     
    210255        }
    211256
    212257        /**
    213          * Get the item's schema, conforming to JSON Schema.
     258         * Gets the item's schema, conforming to JSON Schema.
    214259         *
     260         * @since 4.7.0
     261         *
    215262         * @return array
    216263         */
    217264        public function get_item_schema() {
     
    219266        }
    220267
    221268        /**
    222          * Get the item's schema for display / public consumption purposes.
     269         * Gets the item's schema for display / public consumption purposes.
    223270         *
     271         * @since 4.7.0
     272         *
    224273         * @return array
    225274         */
    226275        public function get_public_item_schema() {
     
    235284        }
    236285
    237286        /**
    238          * Get the query params for collections.
     287         * Gets the query params for collections.
    239288         *
     289         * @since 4.7.0
     290         *
    240291         * @return array
    241292         */
    242293        public function get_collection_params() {
     
    269320        }
    270321
    271322        /**
    272          * Get the magical context param.
     323         * Gets the magical context param.
    273324         *
    274325         * Ensures consistent description between endpoints, and populates enum from schema.
    275326         *
    276          * @param array     $args
     327         * @since 4.7.0
     328         *
     329         * @param array $args Additional arguments for context parameter.
    277330         * @return array
    278331         */
    279332        public function get_context_param( $args = array() ) {
     
    301354        }
    302355
    303356        /**
    304          * Add the values from additional fields to a data object.
     357         * Adds the values from additional fields to a data object.
    305358         *
    306          * @param array  $object
    307          * @param WP_REST_Request $request
     359         * @since 4.7.0
     360         *
     361         * @param array           $object  data object.
     362         * @param WP_REST_Request $request Full details about the request.
    308363         * @return array modified object with additional fields.
    309364         */
    310365        protected function add_additional_fields_to_object( $object, $request ) {
     
    324379        }
    325380
    326381        /**
    327          * Update the values of additional fields added to a data object.
     382         * Updates the values of additional fields added to a data object.
    328383         *
    329          * @param array  $object
    330          * @param WP_REST_Request $request
     384         * @since 4.7.0
     385         *
     386         * @param array           $object  data Object.
     387         * @param WP_REST_Request $request Full details about the request.
    331388         * @return bool|WP_Error True on success, WP_Error object if a field cannot be updated.
    332389         */
    333390        protected function update_additional_fields_for_object( $object, $request ) {
     
    353410        }
    354411
    355412        /**
    356          * Add the schema from additional fields to an schema array.
     413         * Adds the schema from additional fields to an schema array.
    357414         *
    358415         * The type of object is inferred from the passed schema.
    359416         *
     417         * @since 4.7.0
     418         *
    360419         * @param array $schema Schema array.
    361420         * @return array Modified Schema array.
    362421         */
     
    384443        }
    385444
    386445        /**
    387          * Get all the registered additional fields for a given object-type.
     446         * Gets all the registered additional fields for a given object-type.
    388447         *
    389          * @param  string $object_type
     448         * @since 4.7.0
     449         *
     450         * @param  string $object_type Optional, default is null. Type of the Object.
    390451         * @return array
    391452         */
    392453        protected function get_additional_fields( $object_type = null ) {
     
    409470        }
    410471
    411472        /**
    412          * Get the object type this controller is responsible for managing.
     473         * Gets the object type this controller is responsible for managing.
    413474         *
     475         * @since 4.7.0
     476         *
    414477         * @return string
    415478         */
    416479        protected function get_object_type() {
     
    424487        }
    425488
    426489        /**
    427          * Get an array of endpoint arguments from the item schema for the controller.
     490         * Gets an array of endpoint arguments from the item schema for the controller.
    428491         *
     492         * @since 4.7.0
     493         *
    429494         * @param string $method HTTP method of the request. The arguments
    430495         *                       for `CREATABLE` requests are checked for required
    431496         *                       values and may fall-back to a given default, this
     
    479544
    480545                                $endpoint_args[ $field_id ] = array_merge( $endpoint_args[ $field_id ], $params['arg_options'] );
    481546                        }
    482                 }
     547                } // End foreach().
    483548
    484549                return $endpoint_args;
    485550        }
     
    492557         * resultant post object. This is done so that plugins may manipulate the
    493558         * post that is used in the REST API.
    494559         *
     560         * @since 4.7.0
     561         *
    495562         * @see get_post()
    496563         * @global WP_Query $wp_query
    497564         *
     
    502569                $post_obj = get_post( $post );
    503570
    504571                /**
    505                  * Filter the post.
     572                 * Filters the post.
    506573                 *
    507574                 * Allows plugins to filter the post object as returned by `\WP_REST_Controller::get_post()`.
    508575                 *
     
    515582        }
    516583
    517584        /**
    518          * Sanitize the slug value.
     585         * Sanitizes the slug value.
    519586         *
     587         * @since 4.7.0
     588         *
    520589         * @internal We can't use {@see sanitize_title} directly, as the second
    521590         * parameter is the fallback title, which would end up being set to the
    522591         * request object.
  • wp-includes/rest-api/endpoints/class-wp-rest-post-statuses-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Post_Statuses_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
     10/**
     11 * Access post statuses.
     12 *
     13 * @since 4.7.0
     14 */
    315class WP_REST_Post_Statuses_Controller extends WP_REST_Controller {
    416
     17        /**
     18         * Constructor.
     19         *
     20         * @since 4.7.0
     21         */
    522        public function __construct() {
    623                $this->namespace = 'wp/v2';
    724                $this->rest_base = 'statuses';
     
    825        }
    926
    1027        /**
    11          * Register the routes for the objects of the controller.
     28         * Registers the routes for the objects of the controller.
     29         *
     30         * @since 4.7.0
    1231         */
    1332        public function register_routes() {
    1433
     
    3655        }
    3756
    3857        /**
    39          * Check whether a given request has permission to read post statuses.
     58         * Checks whether a given request has permission to read post statuses.
    4059         *
     60         * @since 4.7.0
     61         *
    4162         * @param  WP_REST_Request $request Full details about the request.
    4263         * @return WP_Error|boolean
    4364         */
     
    5576        }
    5677
    5778        /**
    58          * Get all post statuses, depending on user context
     79         * Gets all post statuses, depending on user context.
    5980         *
    60          * @param WP_REST_Request $request
     81         * @since 4.7.0
     82         *
     83         * @param WP_REST_Request $request Full details about the request.
    6184         * @return array|WP_Error
    6285         */
    6386        public function get_items( $request ) {
     
    78101        /**
    79102         * Check if a given request has access to read a post status.
    80103         *
     104         * @since 4.7.0
     105         *
    81106         * @param  WP_REST_Request $request Full details about the request.
    82107         * @return WP_Error|boolean
    83108         */
     
    94119        }
    95120
    96121        /**
    97          * Check whether a given post status should be visible
     122         * Checks whether a given post status should be visible.
    98123         *
    99          * @param object $status
     124         * @since 4.7.0
     125         *
     126         * @param object $status Post status.
    100127         * @return boolean
    101128         */
    102129        protected function check_read_permission( $status ) {
     
    115142        }
    116143
    117144        /**
    118          * Get a specific post status
     145         * Gets a specific post status.
    119146         *
    120          * @param WP_REST_Request $request
     147         * @since 4.7.0
     148         *
     149         * @param WP_REST_Request $request Full details about the request.
    121150         * @return array|WP_Error
    122151         */
    123152        public function get_item( $request ) {
     
    130159        }
    131160
    132161        /**
    133          * Prepare a post status object for serialization
     162         * Prepares a post status object for serialization.
    134163         *
    135          * @param stdClass $status Post status data
    136          * @param WP_REST_Request $request
     164         * @since 4.7.0
     165         *
     166         * @param stdClass        $status  Post status data.
     167         * @param WP_REST_Request $request Full details about the request.
    137168         * @return WP_REST_Response Post status data
    138169         */
    139170        public function prepare_item_for_response( $status, $request ) {
     
    161192                }
    162193
    163194                /**
    164                  * Filter a status returned from the API.
     195                 * Filters a status returned from the API.
    165196                 *
    166197                 * Allows modification of the status data right before it is returned.
    167198                 *
     199                 * @since 4.7.0
     200                 *
    168201                 * @param WP_REST_Response  $response The response object.
    169202                 * @param object            $status   The original status object.
    170203                 * @param WP_REST_Request   $request  Request used to generate the response.
     
    173206        }
    174207
    175208        /**
    176          * Get the Post status' schema, conforming to JSON Schema
     209         * Gets the Post status' schema, conforming to JSON Schema.
    177210         *
     211         * @since 4.7.0
     212         *
    178213         * @return array
    179214         */
    180215        public function get_item_schema() {
     
    231266        }
    232267
    233268        /**
    234          * Get the query params for collections
     269         * Gets the query params for collections.
    235270         *
     271         * @since 4.7.0
     272         *
    236273         * @return array
    237274         */
    238275        public function get_collection_params() {
  • wp-includes/rest-api/endpoints/class-wp-rest-post-types-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Post_Types_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
     10/**
     11 * Access post types.
     12 *
     13 * @since 4.7.0
     14 */
    315class WP_REST_Post_Types_Controller extends WP_REST_Controller {
    416
     17        /**
     18         * Constructor.
     19         *
     20         * @since 4.7.0
     21         */
    522        public function __construct() {
    623                $this->namespace = 'wp/v2';
    724                $this->rest_base = 'types';
     
    825        }
    926
    1027        /**
    11          * Register the routes for the objects of the controller.
     28         * Registers the routes for the objects of the controller.
     29         *
     30         * @since 4.7.0
    1231         */
    1332        public function register_routes() {
    1433
     
    3554        }
    3655
    3756        /**
    38          * Check whether a given request has permission to read types.
     57         * Checks whether a given request has permission to read types.
    3958         *
     59         * @since 4.7.0
     60         *
    4061         * @param  WP_REST_Request $request Full details about the request.
    4162         * @return WP_Error|boolean
    4263         */
     
    5374        }
    5475
    5576        /**
    56          * Get all public post types
     77         * Gets all public post types.
    5778         *
    58          * @param WP_REST_Request $request
     79         * @since 4.7.0
     80         *
     81         * @param WP_REST_Request $request Full details about the request.
    5982         * @return array|WP_Error
    6083         */
    6184        public function get_items( $request ) {
     
    7194        }
    7295
    7396        /**
    74          * Get a specific post type
     97         * Gets a specific post type.
    7598         *
    76          * @param WP_REST_Request $request
     99         * @since 4.7.0
     100         *
     101         * @param WP_REST_Request $request Full details about the request.
    77102         * @return array|WP_Error
    78103         */
    79104        public function get_item( $request ) {
     
    92117        }
    93118
    94119        /**
    95          * Prepare a post type object for serialization
     120         * Prepares a post type object for serialization.
    96121         *
    97          * @param stdClass $post_type Post type data
    98          * @param WP_REST_Request $request
     122         * @since 4.7.0
     123         *
     124         * @param stdClass        $post_type Post type data.
     125         * @param WP_REST_Request $request   Full details about the request.
    99126         * @return WP_REST_Response $response
    100127         */
    101128        public function prepare_item_for_response( $post_type, $request ) {
     
    125152                ) );
    126153
    127154                /**
    128                  * Filter a post type returned from the API.
     155                 * Filters a post type returned from the API.
    129156                 *
    130157                 * Allows modification of the post type data right before it is returned.
    131158                 *
     159                 * @since 4.7.0
     160                 *
    132161                 * @param WP_REST_Response  $response   The response object.
    133162                 * @param object            $item       The original post type object.
    134163                 * @param WP_REST_Request   $request    Request used to generate the response.
     
    137166        }
    138167
    139168        /**
    140          * Get the Post type's schema, conforming to JSON Schema
     169         * Gets the Post type's schema, conforming to JSON Schema.
    141170         *
     171         * @since 4.7.0
     172         *
    142173         * @return array
    143174         */
    144175        public function get_item_schema() {
     
    189220        }
    190221
    191222        /**
    192          * Get the query params for collections
     223         * Gets the query params for collections.
    193224         *
     225         * @since 4.7.0
     226         *
    194227         * @return array
    195228         */
    196229        public function get_collection_params() {
  • wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Posts_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
     10/**
     11 * Access Post.
     12 *
     13 * @since 4.7.0
     14 */
    315class WP_REST_Posts_Controller extends WP_REST_Controller {
    416
    517        /**
    618         * Post type.
    719         *
     20         * @since 4.7.0
    821         * @access protected
    922         * @var string
    1023         */
     
    1326        /**
    1427         * Instance of a post meta fields object.
    1528         *
     29         * @since 4.7.0
    1630         * @access protected
    1731         * @var WP_REST_Post_Meta_Fields
    1832         */
     
    2135        /**
    2236         * Constructor.
    2337         *
     38         * @since 4.7.0
    2439         * @param string $post_type Post type.
    2540         */
    2641        public function __construct( $post_type ) {
     
    3348        }
    3449
    3550        /**
    36          * Register the routes for the objects of the controller.
     51         * Registers the routes for the objects of the controller.
     52         *
     53         * @since 4.7.0
    3754         */
    3855        public function register_routes() {
    3956
     
    86103        }
    87104
    88105        /**
    89          * Check if a given request has access to read /posts.
     106         * Checks if a given request has access to read /posts.
    90107         *
     108         * @since 4.7.0
     109         *
    91110         * @param  WP_REST_Request $request Full details about the request.
    92111         * @return WP_Error|boolean
    93112         */
     
    103122        }
    104123
    105124        /**
    106          * Get a collection of posts.
     125         * Gets a collection of posts.
    107126         *
     127         * @since 4.7.0
     128         *
    108129         * @param WP_REST_Request $request Full details about the request.
    109130         * @return WP_Error|WP_REST_Response
    110131         */
     
    140161                        'status'         => 'post_status',
    141162                );
    142163
    143                 // For each known parameter which is both registered and present in the request,
    144                 // set the parameter's value on the query $args.
     164                /*
     165                 * For each known parameter which is both registered and present
     166                 * in the request, set the parameter's value on the query $args.
     167                 */
    145168                foreach ( $parameter_mappings as $api_param => $wp_param ) {
    146169                        if ( isset( $registered[ $api_param ], $request[ $api_param ] ) ) {
    147170                                $args[ $wp_param ] = $request[ $api_param ];
     
    197220                $args['post_type'] = $this->post_type;
    198221
    199222                /**
    200                  * Filter the query arguments for a request.
     223                 * Filters the query arguments for a request.
    201224                 *
    202225                 * Enables adding extra arguments or setting defaults for a post
    203226                 * collection request.
    204227                 *
     228                 * @since 4.7.0
     229                 *
    205230                 * @see https://developer.wordpress.org/reference/classes/wp_query/
    206231                 *
    207232                 * @param array           $args    Key value array of query var to query value.
     
    300325        }
    301326
    302327        /**
    303          * Check if a given request has access to read a post.
     328         * Checks if a given request has access to read a post.
    304329         *
     330         * @since 4.7.0
     331         *
    305332         * @param  WP_REST_Request $request Full details about the request.
    306333         * @return WP_Error|boolean
    307334         */
     
    333360        }
    334361
    335362        /**
    336          * Can the user access password-protected content?
     363         * Checks if the user can access password-protected content.
    337364         *
    338365         * This method determines whether we need to override the regular password
    339366         * check in core with a filter.
    340367         *
     368         * @since 4.7.0
     369         *
    341370         * @param WP_Post         $post    Post to check against.
    342371         * @param WP_REST_Request $request Request data to check.
    343372         * @return bool True if the user can access password-protected content, false otherwise.
     
    363392        }
    364393
    365394        /**
    366          * Get a single post.
     395         * Gets a single post.
    367396         *
     397         * @since 4.7.0
     398         *
    368399         * @param WP_REST_Request $request Full details about the request.
    369400         * @return WP_Error|WP_REST_Response
    370401         */
     
    387418        }
    388419
    389420        /**
    390          * Check if a given request has access to create a post.
     421         * Checks if a given request has access to create a post.
    391422         *
     423         * @since 4.7.0
     424         *
    392425         * @param  WP_REST_Request $request Full details about the request.
    393426         * @return WP_Error|boolean
    394427         */
     
    411444        }
    412445
    413446        /**
    414          * Create a single post.
     447         * Creates a single post.
    415448         *
     449         * @since 4.7.0
     450         *
    416451         * @param WP_REST_Request $request Full details about the request.
    417452         * @return WP_Error|WP_REST_Response
    418453         */
     
    498533        }
    499534
    500535        /**
    501          * Check if a given request has access to update a post.
     536         * Checks if a given request has access to update a post.
    502537         *
     538         * @since 4.7.0
     539         *
    503540         * @param  WP_REST_Request $request Full details about the request.
    504541         * @return WP_Error|boolean
    505542         */
     
    524561        }
    525562
    526563        /**
    527          * Update a single post.
     564         * Updates a single post.
    528565         *
     566         * @since 4.7.0
     567         *
    529568         * @param WP_REST_Request $request Full details about the request.
    530569         * @return WP_Error|WP_REST_Response
    531570         */
     
    602641        }
    603642
    604643        /**
    605          * Check if a given request has access to delete a post.
     644         * Checks if a given request has access to delete a post.
    606645         *
     646         * @since 4.7.0
     647         *
    607648         * @param  WP_REST_Request $request Full details about the request.
    608649         * @return bool|WP_Error
    609650         */
     
    619660        }
    620661
    621662        /**
    622          * Delete a single post.
     663         * Deletes a single post.
    623664         *
     665         * @since 4.7.0
     666         *
    624667         * @param WP_REST_Request $request Full details about the request.
    625668         * @return WP_REST_Response|WP_Error
    626669         */
     
    640683                }
    641684
    642685                /**
    643                  * Filter whether a post is trashable.
     686                 * Filters whether a post is trashable.
    644687                 *
    645688                 * Return false to disable trash support for the post.
    646689                 *
     690                 * @since 4.7.0
     691                 *
    647692                 * @param boolean $supports_trash Whether the post type support trashing.
    648693                 * @param WP_Post $post           The Post object being considered for trashing support.
    649694                 */
     
    692737        }
    693738
    694739        /**
    695          * Determine the allowed query_vars for a get_items() response and
     740         * Determines the allowed query_vars for a get_items() response and
    696741         * prepare for WP_Query.
    697742         *
     743         * @since 4.7.0
     744         *
    698745         * @param array           $prepared_args Prepared WP_Query arguments.
    699746         * @param WP_REST_Request $request       Full details about the request.
    700747         * @return array          $query_args
     
    706753                foreach ( $valid_vars as $var => $index ) {
    707754                        if ( isset( $prepared_args[ $var ] ) ) {
    708755                                /**
    709                                  * Filter the query_vars used in `get_items` for the constructed query.
     756                                 * Filters the query_vars used in `get_items` for the constructed query.
    710757                                 *
    711758                                 * The dynamic portion of the hook name, $var, refers to the query_var key.
    712759                                 *
     760                                 * @since 4.7.0
     761                                 *
    713762                                 * @param mixed $prepared_args[ $var ] The query_var value.
    714763                                 */
    715764                                $query_args[ $var ] = apply_filters( "rest_query_var-{$var}", $prepared_args[ $var ] );
     
    728777        }
    729778
    730779        /**
    731          * Get all the WP Query vars that are allowed for the API request.
     780         * Gets all the WP Query vars that are allowed for the API request.
    732781         *
     782         * @since 4.7.0
     783         *
    733784         * @param WP_REST_Request $request Full details about the request.
    734785         * @return array
    735786         */
     
    737788                global $wp;
    738789
    739790                /**
    740                  * Filter the publicly allowed query vars.
     791                 * Filters the publicly allowed query vars.
    741792                 *
    742793                 * Allows adjusting of the default query vars that are made public.
    743794                 *
     795                 * @since 4.7.0
     796                 *
    744797                 * @param array  Array of allowed WP_Query query vars.
    745798                 */
    746799                $valid_vars = apply_filters( 'query_vars', $wp->public_query_vars );
     
    748801                $post_type_obj = get_post_type_object( $this->post_type );
    749802                if ( current_user_can( $post_type_obj->cap->edit_posts ) ) {
    750803                        /**
    751                          * Filter the allowed 'private' query vars for authorized users.
     804                         * Filters the allowed 'private' query vars for authorized users.
    752805                         *
    753806                         * If the user has the `edit_posts` capability, we also allow use of
    754807                         * private query parameters, which are only undesirable on the
     
    757810                         * To disable anyway, use
    758811                         * `add_filter( 'rest_private_query_vars', '__return_empty_array' );`
    759812                         *
     813                         * @since 4.7.0
     814                         *
    760815                         * @param array $private_query_vars Array of allowed query vars for authorized users.
    761816                         * }
    762817                         */
     
    781836                $valid_vars = array_merge( $valid_vars, $rest_valid );
    782837
    783838                /**
    784                  * Filter allowed query vars for the REST API.
     839                 * Filters allowed query vars for the REST API.
    785840                 *
    786841                 * This filter allows you to add or remove query vars from the final allowed
    787842                 * list for all requests, including unauthenticated ones. To alter the
    788843                 * vars for editors only, {@see rest_private_query_vars}.
    789844                 *
     845                 * @since 4.7.0
     846                 *
    790847                 * @param array {
    791848                 *    Array of allowed WP_Query query vars.
    792849                 *
     
    800857        }
    801858
    802859        /**
    803          * Check the post_date_gmt or modified_gmt and prepare any post or
     860         * Checks the post_date_gmt or modified_gmt and prepare any post or
    804861         * modified date for single post output.
    805862         *
     863         * @since 4.7.0
     864         *
    806865         * @param string      $date_gmt GMT publication time.
    807866         * @param string|null $date     Optional, default is null. Local publication time.
    808867         * @return string|null ISO8601/RFC3339 formatted datetime.
     
    823882        }
    824883
    825884        /**
    826          * Prepare a single post for create or update.
     885         * Prepares a single post for create or update.
    827886         *
     887         * @since 4.7.0
     888         *
    828889         * @param WP_REST_Request $request Request object.
    829890         * @return WP_Error|stdClass $prepared_post Post object.
    830891         */
     
    9601021                        $prepared_post->ping_status = $request['ping_status'];
    9611022                }
    9621023                /**
    963                  * Filter a post before it is inserted via the REST API.
     1024                 * Filters a post before it is inserted via the REST API.
    9641025                 *
    9651026                 * The dynamic portion of the hook name, $this->post_type, refers to post_type of the post being
    9661027                 * prepared for insertion.
    9671028                 *
     1029                 * @since 4.7.0
     1030                 *
    9681031                 * @param stdClass        $prepared_post An object representing a single post prepared
    9691032                 *                                       for inserting or updating the database.
    9701033                 * @param WP_REST_Request $request       Request object.
     
    9741037        }
    9751038
    9761039        /**
    977          * Determine validity and normalize provided status param.
     1040         * Determines validity and normalize provided status param.
    9781041         *
     1042         * @since 4.7.0
     1043         *
    9791044         * @param string $post_status Post status.
    9801045         * @param object $post_type   Post type.
    9811046         * @return WP_Error|string $post_status
     
    10081073        }
    10091074
    10101075        /**
    1011          * Determine the featured media based on a request param.
     1076         * Determines the featured media based on a request param.
    10121077         *
     1078         * @since 4.7.0
     1079         *
    10131080         * @param int $featured_media Featured Media ID.
    10141081         * @param int $post_id        Post ID.
    10151082         * @return bool|WP_Error
     
    10311098        }
    10321099
    10331100        /**
    1034          * Set the template for a page.
     1101         * Sets the template for a page.
    10351102         *
     1103         * @since 4.7.0
     1104         *
    10361105         * @param string  $template Page template filename.
    10371106         * @param integer $post_id  Post ID.
    10381107         */
     
    10451114        }
    10461115
    10471116        /**
    1048          * Update the post's terms from a REST request.
     1117         * Updates the post's terms from a REST request.
    10491118         *
     1119         * @since 4.7.0
     1120         *
    10501121         * @param  int             $post_id The post ID to update the terms form.
    10511122         * @param  WP_REST_Request $request The request object with post and terms data.
    10521123         * @return null|WP_Error   WP_Error on an error assigning any of the terms.
     
    10681139        }
    10691140
    10701141        /**
    1071          * Check if a given post type should be viewed or managed.
     1142         * Checks if a given post type should be viewed or managed.
    10721143         *
     1144         * @since 4.7.0
     1145         *
    10731146         * @param object|string $post_type Post type name or object.
    10741147         * @return boolean Is post type allowed?
    10751148         */
     
    10861159        }
    10871160
    10881161        /**
    1089          * Check if we can read a post.
     1162         * Checks if we can read a post.
    10901163         *
    10911164         * Correctly handles posts with the inherit status.
    10921165         *
     1166         * @since 4.7.0
     1167         *
    10931168         * @param object $post Post object.
    10941169         * @return boolean Can we read it?
    10951170         */
     
    11251200        }
    11261201
    11271202        /**
    1128          * Check if we can edit a post.
     1203         * Checks if we can edit a post.
    11291204         *
     1205         * @since 4.7.0
     1206         *
    11301207         * @param object $post Post object.
    11311208         * @return boolean Can we edit it?
    11321209         */
     
    11411218        }
    11421219
    11431220        /**
    1144          * Check if we can create a post.
     1221         * Checks if we can create a post.
    11451222         *
     1223         * @since 4.7.0
     1224         *
    11461225         * @param object $post Post object.
    11471226         * @return boolean Can we create it?.
    11481227         */
     
    11571236        }
    11581237
    11591238        /**
    1160          * Check if we can delete a post.
     1239         * Checks if we can delete a post.
    11611240         *
     1241         * @since 4.7.0
     1242         *
    11621243         * @param object $post Post object.
    11631244         * @return boolean Can we delete it?
    11641245         */
     
    11731254        }
    11741255
    11751256        /**
    1176          * Prepare a single post output for response.
     1257         * Prepares a single post output for response.
    11771258         *
     1259         * @since 4.7.0
     1260         *
    11781261         * @param WP_Post         $post    Post object.
    11791262         * @param WP_REST_Request $request Request object.
    11801263         * @return WP_REST_Response $data
     
    13431426                $response->add_links( $this->prepare_links( $post ) );
    13441427
    13451428                /**
    1346                  * Filter the post data for a response.
     1429                 * Filters the post data for a response.
    13471430                 *
    13481431                 * The dynamic portion of the hook name, $this->post_type, refers to post_type of the post being
    13491432                 * prepared for the response.
    13501433                 *
     1434                 * @since 4.7.0
     1435                 *
    13511436                 * @param WP_REST_Response   $response   The response object.
    13521437                 * @param WP_Post            $post       Post object.
    13531438                 * @param WP_REST_Request    $request    Request object.
     
    13561441        }
    13571442
    13581443        /**
    1359          * Overwrite the default protected title format.
     1444         * Overwrites the default protected title format.
    13601445         *
    13611446         * By default WordPress will show password protected posts with a title of
    13621447         * "Protected: %s", as the REST API communicates the protected status of a post
     
    13691454        }
    13701455
    13711456        /**
    1372          * Prepare links for the request.
     1457         * Prepares links for the request.
    13731458         *
     1459         * @since 4.7.0
     1460         *
    13741461         * @param WP_Post $post Post object.
    13751462         * @return array Links for the given post.
    13761463         */
     
    14661553        }
    14671554
    14681555        /**
    1469          * Get the Post's schema, conforming to JSON Schema.
     1556         * Gets the Post's schema, conforming to JSON Schema.
    14701557         *
    14711558         * @return array
    14721559         */
     
    14761563                        '$schema'    => 'http://json-schema.org/draft-04/schema#',
    14771564                        'title'      => $this->post_type,
    14781565                        'type'       => 'object',
    1479                         /*
    1480                          * Base properties for every Post.
    1481                          */
     1566                        // Base properties for every Post.
    14821567                        'properties' => array(
    14831568                                'date'            => array(
    14841569                                        'description' => __( "The date the object was published, in the site's timezone." ),
     
    17951880        }
    17961881
    17971882        /**
    1798          * Get the query params for collections of attachments.
     1883         * Gets the query params for collections of attachments.
    17991884         *
    18001885         * @return array
    18011886         */
     
    19382023        }
    19392024
    19402025        /**
    1941          * Validate whether the user can query private statuses.
     2026         * Validates whether the user can query private statuses.
    19422027         *
     2028         * @since 4.7.0
     2029         *
    19432030         * @param  mixed           $value     Post status.
    19442031         * @param  WP_REST_Request $request   Full details about the request.
    19452032         * @param  string          $parameter
  • wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Revisions_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
     10/**
     11 * Access revisions.
     12 *
     13 * @since 4.7.0
     14 */
    315class WP_REST_Revisions_Controller extends WP_REST_Controller {
    416
     17        /**
     18         * Parent post type.
     19         *
     20         * @since 4.7.0
     21         * @access private
     22         * @var string
     23         */
    524        private $parent_post_type;
     25
     26        /**
     27         * Parent controller.
     28         *
     29         * @since 4.7.0
     30         * @access private
     31         * @var WP_REST_Controller
     32         */
    633        private $parent_controller;
     34
     35        /**
     36         * The base of the parent controller's route.
     37         *
     38         * @since 4.7.0
     39         * @access private
     40         * @var string
     41         */
    742        private $parent_base;
    843
     44        /**
     45         * Constructor.
     46         *
     47         * @since 4.7.0
     48         *
     49         * @param string $parent_post_type Post type of the parent.
     50         */
    951        public function __construct( $parent_post_type ) {
    1052                $this->parent_post_type = $parent_post_type;
    1153                $this->parent_controller = new WP_REST_Posts_Controller( $parent_post_type );
     
    1658        }
    1759
    1860        /**
    19          * Register routes for revisions based on post types supporting revisions
     61         * Registers routes for revisions based on post types supporting revisions.
    2062         *
    21          * @access public
     63         * @since 4.7.0
    2264         */
    2365        public function register_routes() {
    2466
     
    5294        }
    5395
    5496        /**
    55          * Check if a given request has access to get revisions
     97         * Checks if a given request has access to get revisions.
    5698         *
    57          * @access public
     99         * @since 4.7.0
    58100         *
    59101         * @param WP_REST_Request $request Full data about the request.
    60102         * @return WP_Error|boolean
     
    74116        }
    75117
    76118        /**
    77          * Get a collection of revisions
     119         * Gets a collection of revisions.
    78120         *
    79          * @access public
     121         * @since 4.7.0
    80122         *
    81123         * @param WP_REST_Request $request Full data about the request.
    82124         * @return WP_Error|WP_REST_Response
     
    99141        }
    100142
    101143        /**
    102          * Check if a given request has access to get a specific revision
     144         * Checks if a given request has access to get a specific revision.
    103145         *
    104          * @access public
     146         * @since 4.7.0
    105147         *
    106148         * @param WP_REST_Request $request Full data about the request.
    107149         * @return WP_Error|boolean
     
    111153        }
    112154
    113155        /**
    114          * Get one revision from the collection
     156         * Gets one revision from the collection.
    115157         *
    116          * @access public
     158         * @since 4.7.0
    117159         *
    118160         * @param WP_REST_Request $request Full data about the request.
    119161         * @return WP_Error|array
     
    135177        }
    136178
    137179        /**
    138          * Check if a given request has access to delete a revision
     180         * Checks if a given request has access to delete a revision.
    139181         *
    140          * @access public
     182         * @since 4.7.0
    141183         *
    142184         * @param  WP_REST_Request $request Full details about the request.
    143185         * @return WP_Error|boolean
     
    158200        }
    159201
    160202        /**
    161          * Delete a single revision
     203         * Deletes a single revision.
    162204         *
    163          * @access public
     205         * @since 4.7.0
    164206         *
    165207         * @param WP_REST_Request $request Full details about the request.
    166208         * @return WP_Error|boolean
     
    171213                /**
    172214                 * Fires after a revision is deleted via the REST API.
    173215                 *
     216                 * @since 4.7.0
     217                 *
    174218                 * @param (mixed) $result The revision object (if it was deleted or moved to the trash successfully)
    175219                 *                        or false (failure). If the revision was moved to to the trash, $result represents
    176220                 *                        its new state; if it was deleted, $result represents its state before deletion.
     
    186230        }
    187231
    188232        /**
    189          * Prepare the revision for the REST response
     233         * Prepares the revision for the REST response.
    190234         *
    191          * @access public
     235         * @since 4.7.0
    192236         *
    193237         * @param WP_Post         $post    Post revision object.
    194238         * @param WP_REST_Request $request Request object.
     
    273317                }
    274318
    275319                /**
    276                  * Filter a revision returned from the API.
     320                 * Filters a revision returned from the API.
    277321                 *
    278322                 * Allows modification of the revision right before it is returned.
    279323                 *
     
    285329        }
    286330
    287331        /**
    288          * Check the post_date_gmt or modified_gmt and prepare any post or
     332         * Checks the post_date_gmt or modified_gmt and prepare any post or
    289333         * modified date for single post output.
    290334         *
    291335         * @access protected
     
    307351        }
    308352
    309353        /**
    310          * Get the revision's schema, conforming to JSON Schema
     354         * Gets the revision's schema, conforming to JSON Schema.
    311355         *
    312          * @access public
     356         * @since 4.7.0
    313357         *
    314358         * @return array
    315359         */
     
    318362                        '$schema'    => 'http://json-schema.org/draft-04/schema#',
    319363                        'title'      => "{$this->parent_post_type}-revision",
    320364                        'type'       => 'object',
    321                         /*
    322                          * Base properties for every Revision
    323                          */
     365                        // Base properties for every Revision.
    324366                        'properties' => array(
    325367                                'author'          => array(
    326368                                        'description' => __( 'The id for the author of the object.' ),
     
    393435        }
    394436
    395437        /**
    396          * Get the query params for collections
     438         * Gets the query params for collections.
    397439         *
    398          * @access public
     440         * @since 4.7.0
    399441         *
    400442         * @return array
    401443         */
     
    406448        }
    407449
    408450        /**
    409          * Check the post excerpt and prepare it for single post output.
     451         * Checks the post excerpt and prepare it for single post output.
    410452         *
    411453         * @access protected
    412454         *
  • wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Settings_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
    310/**
    411 * Manage a WordPress site's settings.
     12 *
     13 * @since 4.7.0
    514 */
    6 
    715class WP_REST_Settings_Controller extends WP_REST_Controller {
    816
     17        /**
     18         * REST Base for settings.
     19         *
     20         * @access protected
     21         * @var string
     22         */
    923        protected $rest_base = 'settings';
     24
     25        /**
     26         * REST namespace.
     27         *
     28         * @access protected
     29         * @var string
     30         */
    1031        protected $namespace = 'wp/v2';
    1132
    1233        /**
    13          * Register the routes for the objects of the controller.
     34         * Registers the routes for the objects of the controller.
     35         *
     36         * @since 4.7.0
    1437         */
    1538        public function register_routes() {
    1639                register_rest_route( $this->namespace, '/' . $this->rest_base, array(
     
    3154        }
    3255
    3356        /**
    34          * Check if a given request has access to read and manage settings.
     57         * Checks if a given request has access to read and manage settings.
    3558         *
     59         * @since 4.7.0
     60         *
    3661         * @param  WP_REST_Request $request Full details about the request.
    3762         * @return boolean
    3863         */
     
    4166        }
    4267
    4368        /**
    44          * Get the settings.
     69         * Gets the settings.
    4570         *
     71         * @since 4.7.0
     72         *
    4673         * @param WP_REST_Request $request Full details about the request.
    4774         * @return WP_Error|array
    4875         */
     
    81108        }
    82109
    83110        /**
    84          * Prepare a value for output based off a schema array.
     111         * Prepares a value for output based off a schema array.
    85112         *
    86          * @param  mixed $value
    87          * @param  array $schema
     113         * @since 4.7.0
     114         *
     115         * @param  mixed $value  Value to prepare.
     116         * @param  array $schema Schema to match.
    88117         * @return mixed
    89118         */
    90119        protected function prepare_value( $value, $schema ) {
     
    101130        }
    102131
    103132        /**
    104          * Update settings for the settings object.
     133         * Updates settings for the settings object.
    105134         *
     135         * @since 4.7.0
     136         *
    106137         * @param  WP_REST_Request $request Full detail about the request.
    107138         * @return WP_Error|array
    108139         */
     
    147178        }
    148179
    149180        /**
    150          * Get all the registered options for the Settings API
     181         * Gets all the registered options for the Settings API.
    151182         *
     183         * @since 4.7.0
     184         *
    152185         * @return array
    153186         */
    154187        protected function get_registered_options() {
     
    191224                        }
    192225
    193226                        $rest_options[ $rest_args['name'] ] = $rest_args;
    194                 }
     227                } // End foreach().
    195228
    196229                return $rest_options;
    197230        }
    198231
    199232        /**
    200          * Get the site setting schema, conforming to JSON Schema.
     233         * Gets the site setting schema, conforming to JSON Schema.
    201234         *
     235         * @since 4.7.0
     236         *
    202237         * @return array
    203238         */
    204239        public function get_item_schema() {
  • wp-includes/rest-api/endpoints/class-wp-rest-taxonomies-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Taxonomies_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
     10/**
     11 * Access taxonomies.
     12 *
     13 * @since 4.7.0
     14 */
    315class WP_REST_Taxonomies_Controller extends WP_REST_Controller {
    416
     17        /**
     18         * Constructor.
     19         *
     20         * @since 4.7.0
     21         */
    522        public function __construct() {
    623                $this->namespace = 'wp/v2';
    724                $this->rest_base = 'taxonomies';
     
    825        }
    926
    1027        /**
    11          * Register the routes for the objects of the controller.
     28         * Registers the routes for the objects of the controller.
     29         *
     30         * @since 4.7.0
    1231         */
    1332        public function register_routes() {
    1433
     
    3655        }
    3756
    3857        /**
    39          * Check whether a given request has permission to read taxonomies.
     58         * Checks whether a given request has permission to read taxonomies.
    4059         *
     60         * @since 4.7.0
     61         *
    4162         * @param  WP_REST_Request $request Full details about the request.
    4263         * @return WP_Error|boolean
    4364         */
     
    5980        }
    6081
    6182        /**
    62          * Get all public taxonomies
     83         * Gets all public taxonomies.
    6384         *
    64          * @param WP_REST_Request $request
     85         * @since 4.7.0
     86         *
     87         * @param WP_REST_Request $request Full details about the request.
    6588         * @return array
    6689         */
    6790        public function get_items( $request ) {
     
    93116        }
    94117
    95118        /**
    96          * Check if a given request has access a taxonomy
     119         * Checks if a given request has access a taxonomy.
    97120         *
     121         * @since 4.7.0
     122         *
    98123         * @param  WP_REST_Request $request Full details about the request.
    99124         * @return WP_Error|boolean
    100125         */
     
    115140        }
    116141
    117142        /**
    118          * Get a specific taxonomy
     143         * Gets a specific taxonomy.
    119144         *
    120          * @param WP_REST_Request $request
     145         * @since 4.7.0
     146         *
     147         * @param WP_REST_Request $request Full details about the request.
    121148         * @return array|WP_Error
    122149         */
    123150        public function get_item( $request ) {
     
    130157        }
    131158
    132159        /**
    133          * Prepare a taxonomy object for serialization
     160         * Prepares a taxonomy object for serialization.
    134161         *
    135          * @param stdClass $taxonomy Taxonomy data
    136          * @param WP_REST_Request $request
     162         * @since 4.7.0
     163         *
     164         * @param stdClass        $taxonomy Taxonomy data.
     165         * @param WP_REST_Request $request  Full details about the request.
    137166         * @return WP_REST_Response $response
    138167         */
    139168        public function prepare_item_for_response( $taxonomy, $request ) {
     
    167196                ) );
    168197
    169198                /**
    170                  * Filter a taxonomy returned from the API.
     199                 * Filters a taxonomy returned from the API.
    171200                 *
    172201                 * Allows modification of the taxonomy data right before it is returned.
    173202                 *
     203                 * @since 4.7.0
     204                 *
    174205                 * @param WP_REST_Response  $response   The response object.
    175206                 * @param object            $item       The original taxonomy object.
    176207                 * @param WP_REST_Request   $request    Request used to generate the response.
     
    179210        }
    180211
    181212        /**
    182          * Get the taxonomy's schema, conforming to JSON Schema
     213         * Gets the taxonomy's schema, conforming to JSON Schema.
    183214         *
     215         * @since 4.7.0
     216         *
    184217         * @return array
    185218         */
    186219        public function get_item_schema() {
     
    243276        }
    244277
    245278        /**
    246          * Get the query params for collections
     279         * Gets the query params for collections.
    247280         *
     281         * @since 4.7.0
     282         *
    248283         * @return array
    249284         */
    250285        public function get_collection_params() {
  • wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Terms_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
    310/**
    411 * Access terms associated with a taxonomy.
     12 *
     13 * @since 4.7.0
    514 */
    615class WP_REST_Terms_Controller extends WP_REST_Controller {
    716
     
    817        /**
    918         * Taxonomy key.
    1019         *
     20         * @since 4.7.0
    1121         * @access protected
    1222         * @var string
    1323         */
     
    1626        /**
    1727         * Instance of a term meta fields object.
    1828         *
     29         * @since 4.7.0
    1930         * @access protected
    2031         * @var WP_REST_Term_Meta_Fields
    2132         */
     
    2435        /**
    2536         * Column to have the terms be sorted by.
    2637         *
     38         * @since 4.7.0
    2739         * @access protected
    2840         * @var string
    2941         */
     
    3244        /**
    3345         * Number of terms that were found.
    3446         *
     47         * @since 4.7.0
    3548         * @access protected
    3649         * @var int
    3750         */
     
    4053        /**
    4154         * Constructor.
    4255         *
     56         * @since 4.7.0
     57         *
    4358         * @param string $taxonomy Taxonomy key.
    4459         */
    4560        public function __construct( $taxonomy ) {
     
    5368
    5469        /**
    5570         * Registers the routes for the objects of the controller.
     71         *
     72         * @since 4.7.0
    5673         */
    5774        public function register_routes() {
    5875
     
    104121        /**
    105122         * Checks if a request has access to read terms in the specified taxonomy.
    106123         *
     124         * @since 4.7.0
     125         *
    107126         * @param  WP_REST_Request $request Full details about the request.
    108127         * @return WP_Error|boolean
    109128         */
     
    121140        /**
    122141         * Gets terms associated with a taxonomy.
    123142         *
     143         * @since 4.7.0
     144         *
    124145         * @param WP_REST_Request $request Full details about the request.
    125146         * @return WP_REST_Response|WP_Error
    126147         */
     
    198219                        unset( $count_args['number'], $count_args['offset'] );
    199220                        $total_terms = wp_count_terms( $this->taxonomy, $count_args );
    200221
    201                         // wp_count_terms can return a falsy value when the term has no children
     222                        // wp_count_terms can return a falsy value when the term has no children.
    202223                        if ( ! $total_terms ) {
    203224                                $total_terms = 0;
    204225                        }
     
    245266         * supported, notably `include`, `exclude`. In `self::get_items()` these
    246267         * are instead treated as a full query.
    247268         *
     269         * @since 4.7.0
     270         *
    248271         * @param array $prepared_args Arguments for get_terms().
    249272         * @return array List of term objects. (Total count in `$this->total_terms`)
    250273         */
     
    286309        }
    287310
    288311        /**
    289          * Comparison function for sorting terms by a column.
     312         * Compares terms for sorting by a column.
    290313         *
    291314         * Uses `$this->sort_column` to determine field to sort by.
    292315         *
    293          * @access protected
     316         * @since 4.7.0
    294317         *
    295318         * @param stdClass $left Term object.
    296319         * @param stdClass $right Term object.
     
    311334        /**
    312335         * Checks if a request has access to read the specified term.
    313336         *
     337         * @since 4.7.0
     338         *
    314339         * @param  WP_REST_Request $request Full details about the request.
    315340         * @return WP_Error|boolean
    316341         */
     
    328353        /**
    329354         * Gets a single term from a taxonomy.
    330355         *
    331          * @param WP_REST_Request $request Full details about the request
     356         * @since 4.7.0
     357         *
     358         * @param WP_REST_Request $request Full details about the request.
    332359         * @return WP_REST_Request|WP_Error
    333360         */
    334361        public function get_item( $request ) {
     
    349376        /**
    350377         * Checks if a request has access to create a term.
    351378         *
     379         * @since 4.7.0
     380         *
    352381         * @param  WP_REST_Request $request Full details about the request.
    353382         * @return WP_Error|boolean
    354383         */
     
    369398        /**
    370399         * Creates a single term in a taxonomy.
    371400         *
    372          * @param WP_REST_Request $request Full details about the request
     401         * @since 4.7.0
     402         *
     403         * @param WP_REST_Request $request Full details about the request.
    373404         * @return WP_REST_Request|WP_Error
    374405         */
    375406        public function create_item( $request ) {
     
    389420
    390421                $term = wp_insert_term( $prepared_term->name, $this->taxonomy, $prepared_term );
    391422                if ( is_wp_error( $term ) ) {
    392 
    393423                        /*
    394424                         * If we're going to inform the client that the term already exists,
    395425                         * give them the identifier for future use.
     
    407437                /**
    408438                 * Fires after a single term is created or updated via the REST API.
    409439                 *
     440                 * @since 4.7.0
     441                 *
    410442                 * @param WP_Term         $term     Inserted Term object.
    411443                 * @param WP_REST_Request $request  Request object.
    412444                 * @param boolean         $creating True when creating term, false when updating.
     
    437469        /**
    438470         * Checks if a request has access to update the specified term.
    439471         *
     472         * @since 4.7.0
     473         *
    440474         * @param  WP_REST_Request $request Full details about the request.
    441475         * @return WP_Error|boolean
    442476         */
     
    462496        /**
    463497         * Updates a single term from a taxonomy.
    464498         *
    465          * @param WP_REST_Request $request Full details about the request
     499         * @since 4.7.0
     500         *
     501         * @param WP_REST_Request $request Full details about the request.
    466502         * @return WP_REST_Request|WP_Error
    467503         */
    468504        public function update_item( $request ) {
     
    516552        /**
    517553         * Checks if a request has access to delete the specified term.
    518554         *
     555         * @since 4.7.0
     556         *
    519557         * @param  WP_REST_Request $request Full details about the request.
    520558         * @return WP_Error|boolean
    521559         */
     
    537575        /**
    538576         * Deletes a single term from a taxonomy.
    539577         *
    540          * @param WP_REST_Request $request Full details about the request
     578         * @since 4.7.0
     579         *
     580         * @param WP_REST_Request $request Full details about the request.
    541581         * @return WP_REST_Response|WP_Error
    542582         */
    543583        public function delete_item( $request ) {
     
    573613        /**
    574614         * Prepares a single term for create or update.
    575615         *
     616         * @since 4.7.0
     617         *
    576618         * @param WP_REST_Request $request Request object.
    577619         * @return object $prepared_term Term object.
    578620         */
     
    610652                /**
    611653                 * Filters term data before inserting term via the REST API.
    612654                 *
     655                 * @since 4.7.0
     656                 *
    613657                 * @param object          $prepared_term Term object.
    614658                 * @param WP_REST_Request $request       Request object.
    615659                 */
     
    619663        /**
    620664         * Prepares a single term output for response.
    621665         *
     666         * @since 4.7.0
     667         *
    622668         * @param obj             $item    Term object.
    623669         * @param WP_REST_Request $request Request object.
    624670         * @return WP_REST_Response $response
     
    668714                 *
    669715                 * Allows modification of the term data right before it is returned.
    670716                 *
     717                 * @since 4.7.0
     718                 *
    671719                 * @param WP_REST_Response  $response  The response object.
    672720                 * @param object            $item      The original term object.
    673721                 * @param WP_REST_Request   $request   Request used to generate the response.
     
    678726        /**
    679727         * Prepares links for the request.
    680728         *
     729         * @since 4.7.0
     730         *
    681731         * @param object $term Term object.
    682732         * @return array Links for the given term.
    683733         */
     
    731781        /**
    732782         * Gets the term's schema, conforming to JSON Schema.
    733783         *
     784         * @since 4.7.0
     785         *
    734786         * @return array
    735787         */
    736788        public function get_item_schema() {
     
    808860        /**
    809861         * Gets the query params for collections.
    810862         *
     863         * @since 4.7.0
     864         *
    811865         * @return array
    812866         */
    813867        public function get_collection_params() {
     
    894948        /**
    895949         * Checks that the taxonomy is valid.
    896950         *
     951         * @since 4.7.0
     952         *
    897953         * @param string $taxonomy Taxonomy to check.
    898954         * @return WP_Error|boolean
    899955         */
  • wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Users_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
    310/**
    4  * Access users
     11 * Access users.
     12 *
     13 * @since 4.7.0
    514 */
    615class WP_REST_Users_Controller extends WP_REST_Controller {
    716
     
    817        /**
    918         * Instance of a user meta fields object.
    1019         *
     20         * @since 4.7.0
    1121         * @access protected
    1222         * @var WP_REST_User_Meta_Fields
    1323         */
    1424        protected $meta;
    1525
     26        /**
     27         * Constructor.
     28         *
     29         * @since 4.7.0
     30         */
    1631        public function __construct() {
    1732                $this->namespace = 'wp/v2';
    1833                $this->rest_base = 'users';
     
    2136        }
    2237
    2338        /**
    24          * Register the routes for the objects of the controller.
     39         * Registers the routes for the objects of the controller.
     40         *
     41         * @since 4.7.0
    2542         */
    2643        public function register_routes() {
    2744
     
    83100        /**
    84101         * Permissions check for getting all users.
    85102         *
     103         * @since 4.7.0
     104         *
    86105         * @param WP_REST_Request $request Full details about the request.
    87106         * @return WP_Error|boolean
    88107         */
     
    104123        }
    105124
    106125        /**
    107          * Get all users
     126         * Gets all users.
    108127         *
     128         * @since 4.7.0
     129         *
    109130         * @param WP_REST_Request $request Full details about the request.
    110131         * @return WP_Error|WP_REST_Response
    111132         */
     
    170191                }
    171192
    172193                /**
    173                  * Filter arguments, before passing to WP_User_Query, when querying users via the REST API.
     194                 * Filters arguments, before passing to WP_User_Query, when querying users via the REST API.
    174195                 *
     196                 * @since 4.7.0
     197                 *
    175198                 * @see https://developer.wordpress.org/reference/classes/wp_user_query/
    176199                 *
    177200                 * @param array           $prepared_args Array of arguments for WP_User_Query.
     
    197220
    198221                $total_users = $query->get_total();
    199222                if ( $total_users < 1 ) {
    200                         // Out-of-bounds, run the query again without LIMIT for total count
     223                        // Out-of-bounds, run the query again without LIMIT for total count.
    201224                        unset( $prepared_args['number'], $prepared_args['offset'] );
    202225                        $count_query = new WP_User_Query( $prepared_args );
    203226                        $total_users = $count_query->get_total();
     
    225248        }
    226249
    227250        /**
    228          * Check if a given request has access to read a user
     251         * Checks if a given request has access to read a user.
    229252         *
     253         * @since 4.7.0
     254         *
    230255         * @param  WP_REST_Request $request Full details about the request.
    231256         * @return WP_Error|boolean
    232257         */
     
    254279        }
    255280
    256281        /**
    257          * Get a single user
     282         * Gets a single user.
    258283         *
     284         * @since 4.7.0
     285         *
    259286         * @param WP_REST_Request $request Full details about the request.
    260287         * @return WP_Error|WP_REST_Response
    261288         */
     
    274301        }
    275302
    276303        /**
    277          * Get the current user
     304         * Gets the current user.
    278305         *
     306         * @since 4.7.0
     307         *
    279308         * @param WP_REST_Request $request Full details about the request.
    280309         * @return WP_Error|WP_REST_Response
    281310         */
     
    295324        }
    296325
    297326        /**
    298          * Check if a given request has access create users
     327         * Checks if a given request has access create users.
    299328         *
     329         * @since 4.7.0
     330         *
    300331         * @param  WP_REST_Request $request Full details about the request.
    301332         * @return WP_Error|boolean
    302333         */
     
    310341        }
    311342
    312343        /**
    313          * Create a single user
     344         * Creates a single user.
    314345         *
     346         * @since 4.7.0
     347         *
    315348         * @param WP_REST_Request $request Full details about the request.
    316349         * @return WP_Error|WP_REST_Response
    317350         */
     
    375408                /**
    376409                 * Fires after a user is created or updated via the REST API.
    377410                 *
     411                 * @since 4.7.0
     412                 *
    378413                 * @param WP_User         $user      Data used to create the user.
    379414                 * @param WP_REST_Request $request   Request object.
    380415                 * @param boolean         $creating  True when creating user, false when updating user.
     
    391426        }
    392427
    393428        /**
    394          * Check if a given request has access update a user
     429         * Checks if a given request has access update a user.
    395430         *
     431         * @since 4.7.0
     432         *
    396433         * @param  WP_REST_Request $request Full details about the request.
    397434         * @return WP_Error|boolean
    398435         */
     
    412449        }
    413450
    414451        /**
    415          * Update a single user
     452         * Updates a single user.
    416453         *
     454         * @since 4.7.0
     455         *
    417456         * @param WP_REST_Request $request Full details about the request.
    418457         * @return WP_Error|WP_REST_Response
    419458         */
     
    446485
    447486                $user = $this->prepare_item_for_database( $request );
    448487
    449                 // Ensure we're operating on the same user we already checked
     488                // Ensure we're operating on the same user we already checked.
    450489                $user->ID = $id;
    451490
    452491                $user_id = wp_update_user( $user );
     
    482521        }
    483522
    484523        /**
    485          * Check if a given request has access delete a user
     524         * Checks if a given request has access delete a user.
    486525         *
     526         * @since 4.7.0
     527         *
    487528         * @param  WP_REST_Request $request Full details about the request.
    488529         * @return WP_Error|boolean
    489530         */
     
    499540        }
    500541
    501542        /**
    502          * Delete a single user
     543         * Deletes a single user.
    503544         *
     545         * @since 4.7.0
     546         *
    504547         * @param WP_REST_Request $request Full details about the request.
    505548         * @return WP_Error|WP_REST_Response
    506549         */
     
    509552                $reassign = isset( $request['reassign'] ) ? absint( $request['reassign'] ) : null;
    510553                $force = isset( $request['force'] ) ? (bool) $request['force'] : false;
    511554
    512                 // We don't support trashing for this type, error out
     555                // We don't support trashing for this type, error out.
    513556                if ( ! $force ) {
    514557                        return new WP_Error( 'rest_trash_not_supported', __( 'Users do not support trashing.' ), array( 'status' => 501 ) );
    515558                }
     
    540583                /**
    541584                 * Fires after a user is deleted via the REST API.
    542585                 *
     586                 * @since 4.7.0
     587                 *
    543588                 * @param WP_User          $user     The user data.
    544589                 * @param WP_REST_Response $response The response returned from the API.
    545590                 * @param WP_REST_Request  $request  The request sent to the API.
     
    550595        }
    551596
    552597        /**
    553          * Prepare a single user output for response
     598         * Prepares a single user output for response.
    554599         *
    555          * @param object $user User object.
     600         * @since 4.7.0
     601         *
     602         * @param object          $user    User object.
    556603         * @param WP_REST_Request $request Request object.
    557604         * @return WP_REST_Response $response Response data.
    558605         */
     
    634681                $data = $this->add_additional_fields_to_object( $data, $request );
    635682                $data = $this->filter_response_by_context( $data, $context );
    636683
    637                 // Wrap the data in a response object
     684                // Wrap the data in a response object.
    638685                $response = rest_ensure_response( $data );
    639686
    640687                $response->add_links( $this->prepare_links( $user ) );
    641688
    642689                /**
    643                  * Filter user data returned from the REST API.
     690                 * Filters user data returned from the REST API.
    644691                 *
     692                 * @since 4.7.0
     693                 *
    645694                 * @param WP_REST_Response $response  The response object.
    646695                 * @param object           $user      User object used to create response.
    647696                 * @param WP_REST_Request  $request   Request object.
     
    650699        }
    651700
    652701        /**
    653          * Prepare links for the request.
     702         * Prepares links for the request.
    654703         *
     704         * @since 4.7.0
     705         *
    655706         * @param WP_Post $user User object.
    656707         * @return array Links for the given user.
    657708         */
     
    669720        }
    670721
    671722        /**
    672          * Prepare a single user for create or update
     723         * Prepares a single user for create or update.
    673724         *
     725         * @since 4.7.0
     726         *
    674727         * @param WP_REST_Request $request Request object.
    675728         * @return object $prepared_user User object.
    676729         */
     
    723776                }
    724777
    725778                /**
    726                  * Filter user data before inserting user via the REST API.
     779                 * Filters user data before inserting user via the REST API.
    727780                 *
     781                 * @since 4.7.0
     782                 *
    728783                 * @param object          $prepared_user User object.
    729784                 * @param WP_REST_Request $request       Request object.
    730785                 */
     
    732787        }
    733788
    734789        /**
    735          * Determine if the current user is allowed to make the desired roles change.
     790         * Determines if the current user is allowed to make the desired roles change.
    736791         *
     792         * @since 4.7.0
     793         *
    737794         * @param integer $user_id User ID.
    738795         * @param array   $roles   New user roles.
    739796         * @return WP_Error|boolean
     
    754811                                return new WP_Error( 'rest_user_invalid_role', __( 'You cannot give resource that role.' ), array( 'status' => rest_authorization_required_code() ) );
    755812                        }
    756813
    757                         // The new role must be editable by the logged-in user.
    758 
    759814                        /** Include admin functions to get access to get_editable_roles() */
    760815                        require_once ABSPATH . 'wp-admin/includes/admin.php';
    761816
     817                        // The new role must be editable by the logged-in user.
    762818                        $editable_roles = get_editable_roles();
    763819                        if ( empty( $editable_roles[ $role ] ) ) {
    764820                                return new WP_Error( 'rest_user_invalid_role', __( 'You cannot give resource that role.' ), array( 'status' => 403 ) );
     
    766822                }
    767823
    768824                return true;
    769 
    770825        }
    771826
    772827        /**
    773          * Get the User's schema, conforming to JSON Schema
     828         * Gets the User's schema, conforming to JSON Schema.
    774829         *
     830         * @since 4.7.0
     831         *
    775832         * @return array
    776833         */
    777834        public function get_item_schema() {
     
    878935                                'password'        => array(
    879936                                        'description' => __( 'Password for the resource (never included).' ),
    880937                                        'type'        => 'string',
    881                                         'context'     => array(), // Password is never displayed
     938                                        'context'     => array(), // Password is never displayed.
    882939                                        'required'    => true,
    883940                                ),
    884941                                'capabilities'    => array(
     
    924981        }
    925982
    926983        /**
    927          * Get the query params for collections
     984         * Gets the query params for collections.
    928985         *
     986         * @since 4.7.0
     987         *
    929988         * @return array
    930989         */
    931990        public function get_collection_params() {
  • wp-includes/rest-api/fields/class-wp-rest-comment-meta-fields.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Comment_Meta_Fields class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
     10/**
     11 * Manage meta values for comments.
     12 *
     13 * @since 4.7.0
     14 */
    315class WP_REST_Comment_Meta_Fields extends WP_REST_Meta_Fields {
     16
    417        /**
    518         * Get the object type for meta.
    619         *
     20         * @since 4.7.0
     21         *
    722         * @return string
    823         */
    924        protected function get_meta_type() {
     
    1328        /**
    1429         * Get the type for `register_rest_field`.
    1530         *
     31         * @since 4.7.0
     32         *
    1633         * @return string
    1734         */
    1835        public function get_rest_field_type() {
  • wp-includes/rest-api/fields/class-wp-rest-meta-fields.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Meta_Fields class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
    310/**
    411 * Manage meta values for an object.
     12 *
     13 * @since 4.7.0
    514 */
    615abstract class WP_REST_Meta_Fields {
    716
     
    817        /**
    918         * Get the object type for meta.
    1019         *
     20         * @since 4.7.0
     21         *
    1122         * @return string One of 'post', 'comment', 'term', 'user', or anything
    1223         *                else supported by `_get_meta_table()`.
    1324         */
     
    1627        /**
    1728         * Get the object type for `register_rest_field`.
    1829         *
     30         * @since 4.7.0
     31         *
    1932         * @return string Custom post type, 'taxonomy', 'comment', or `user`.
    2033         */
    2134        abstract protected function get_rest_field_type();
     
    2235
    2336        /**
    2437         * Register the meta field.
     38         *
     39         * @since 4.7.0
    2540         */
    2641        public function register_field() {
    2742                register_rest_field( $this->get_rest_field_type(), 'meta', array(
     
    3449        /**
    3550         * Get the `meta` field value.
    3651         *
     52         * @since 4.7.0
     53         *
    3754         * @param int             $object_id Object ID to fetch meta for.
    3855         * @param WP_REST_Request $request   Full details about the request.
    3956         * @return WP_Error|object
     
    7188         * the database, such as booleans. We need to cast back to the relevant
    7289         * type before passing back to JSON.
    7390         *
     91         * @since 4.7.0
     92         *
    7493         * @param mixed           $value   Value to prepare.
    7594         * @param WP_REST_Request $request Current request object.
    7695         * @param array           $args    Options for the field.
     
    87106        /**
    88107         * Update meta values.
    89108         *
     109         * @since 4.7.0
     110         *
    90111         * @param WP_REST_Request $request    Full details about the request.
    91112         * @param int             $object_id  Object ID to fetch meta for.
    92113         * @return WP_Error|null Error if one occurs, null on success.
     
    120141        /**
    121142         * Delete meta value for an object.
    122143         *
     144         * @since 4.7.0
     145         *
    123146         * @param int    $object_id Object ID the field belongs to.
    124147         * @param string $name      Key for the field.
    125148         * @return bool|WP_Error True if meta field is deleted, error otherwise.
     
    149172         *
    150173         * Alters the list of values in the database to match the list of provided values.
    151174         *
     175         * @since 4.7.0
     176         *
    152177         * @param int    $object_id Object ID to update.
    153178         * @param string $name      Key for the custom field.
    154179         * @param array  $values    List of values to update to.
     
    211236        /**
    212237         * Update meta value for an object.
    213238         *
     239         * @since 4.7.0
     240         *
    214241         * @param int    $object_id Object ID to update.
    215242         * @param string $name      Key for the custom field.
    216243         * @param mixed  $value     Updated value.
     
    251278        /**
    252279         * Get all the registered meta fields.
    253280         *
     281         * @since 4.7.0
     282         *
    254283         * @return array
    255284         */
    256285        protected function get_registered_fields() {
     
    305334        /**
    306335         * Get the object's `meta` schema, conforming to JSON Schema.
    307336         *
     337         * @since 4.7.0
     338         *
    308339         * @return array
    309340         */
    310341        public function get_field_schema() {
     
    330361         * Default preparation for meta fields. Override by passing the
    331362         * `prepare_callback` in your `show_in_rest` options.
    332363         *
     364         * @since 4.7.0
     365         *
    333366         * @param mixed           $value   Meta value from the database.
    334367         * @param WP_REST_Request $request Request object.
    335368         * @param array           $args    REST-specific options for the meta key.
  • wp-includes/rest-api/fields/class-wp-rest-post-meta-fields.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Post_Meta_Fields class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
     10/**
     11 * Manage meta values for posts.
     12 *
     13 * @since 4.7.0
     14 */
    315class WP_REST_Post_Meta_Fields extends WP_REST_Meta_Fields {
     16
    417        /**
    518         * Post type to register fields for.
    619         *
     20         * @since 4.7.0
     21         * @access protected
    722         * @var string
    823         */
    924        protected $post_type;
     
    1126        /**
    1227         * Constructor.
    1328         *
     29         * @since 4.7.0
     30         *
    1431         * @param string $post_type Post type to register fields for.
    1532         */
    1633        public function __construct( $post_type ) {
     
    2037        /**
    2138         * Get the object type for meta.
    2239         *
     40         * @since 4.7.0
     41         *
    2342         * @return string
    2443         */
    2544        protected function get_meta_type() {
     
    2948        /**
    3049         * Get the type for `register_rest_field`.
    3150         *
     51         * @since 4.7.0
     52         *
    3253         * @return string Custom post type slug.
    3354         */
    3455        public function get_rest_field_type() {
  • wp-includes/rest-api/fields/class-wp-rest-term-meta-fields.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Term_Meta_Fields class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
    310/**
    411 * Manage meta values for terms.
     12 *
     13 * @since 4.7.0
    514 */
    615class WP_REST_Term_Meta_Fields extends WP_REST_Meta_Fields {
     16
    717        /**
    818         * Taxonomy to register fields for.
    919         *
     20         * @since 4.7.0
     21         * @access protected
    1022         * @var string
    1123         */
    1224        protected $taxonomy;
     25
    1326        /**
    1427         * Constructor.
    1528         *
     29         * @since 4.7.0
     30         *
    1631         * @param string $taxonomy Taxonomy to register fields for.
    1732         */
    1833        public function __construct( $taxonomy ) {
     
    2237        /**
    2338         * Get the object type for meta.
    2439         *
     40         * @since 4.7.0
     41         *
    2542         * @return string
    2643         */
    2744        protected function get_meta_type() {
     
    3148        /**
    3249         * Get the type for `register_rest_field`.
    3350         *
     51         * @since 4.7.0
     52         *
    3453         * @return string
    3554         */
    3655        public function get_rest_field_type() {
  • wp-includes/rest-api/fields/class-wp-rest-user-meta-fields.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_User_Meta_Fields class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
     10/**
     11 * Manage meta values for users.
     12 *
     13 * @since 4.7.0
     14 */
    315class WP_REST_User_Meta_Fields extends WP_REST_Meta_Fields {
     16
    417        /**
    518         * Get the object type for meta.
    619         *
     20         * @since 4.7.0
     21         *
    722         * @return string
    823         */
    924        protected function get_meta_type() {
     
    1328        /**
    1429         * Get the type for `register_rest_field`.
    1530         *
     31         * @since 4.7.0
     32         *
    1633         * @return string
    1734         */
    1835        public function get_rest_field_type() {