Upstream
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

REST API: Corrections and improvements to docblocks for REST API filters. 

See #51800

Built from https://develop.svn.wordpress.org/trunk@49955


git-svn-id: http://core.svn.wordpress.org/trunk@49654 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
John Blackbourn 2021-01-10 22:23:09 +00:00
parent 9b44c28f78
commit 35e1b34f8e
13 changed files with 50 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
wp-includes/rest-api/class-wp-rest-request.php
View File

@ -339,7 +339,7 @@ class WP_REST_Request implements ArrayAccess {
/**
* Retrieves the parameter priority order.
*
* Used when checking parameters in get_param().
* Used when checking parameters in WP_REST_Request::get_param().
*
* @since 4.4.0
*
@ -371,10 +371,10 @@ class WP_REST_Request implements ArrayAccess {
$order[] = 'defaults';
/**
* Filters the parameter order.
* Filters the parameter priority order for a REST API request.
*
* The order affects which parameters are checked when using get_param() and family.
* This acts similarly to PHP's `request_order` setting.
* The order affects which parameters are checked when using WP_REST_Request::get_param()
* and family. This acts similarly to PHP's `request_order` setting.
*
* @since 4.4.0
*
@ -1035,7 +1035,7 @@ class WP_REST_Request implements ArrayAccess {
}
/**
* Filters the request generated from a URL.
* Filters the REST API request generated from a URL.
*
* @since 4.5.0
*

46
wp-includes/rest-api/class-wp-rest-server.php
View File

@ -162,7 +162,7 @@ class WP_REST_Server {
*/
public function check_authentication() {
/**
* Filters REST authentication errors.
* Filters REST API authentication errors.
*
* This is used to pass a WP_Error from an authentication method back to
* the API.
@ -310,11 +310,11 @@ class WP_REST_Server {
$expose_headers = array( 'X-WP-Total', 'X-WP-TotalPages', 'Link' );
/**
* Filters the list of response headers that are exposed to CORS requests.
* Filters the list of response headers that are exposed to REST API CORS requests.
*
* @since 5.5.0
*
* @param string[] $expose_headers The list of headers to expose.
* @param string[] $expose_headers The list of response headers to expose.
*/
$expose_headers = apply_filters( 'rest_exposed_cors_headers', $expose_headers );
@ -329,7 +329,7 @@ class WP_REST_Server {
);
/**
* Filters the list of request headers that are allowed for CORS requests.
* Filters the list of request headers that are allowed for REST API CORS requests.
*
* The allowed headers are passed to the browser to specify which
* headers can be passed to the REST API. By default, we allow the
@ -338,14 +338,14 @@ class WP_REST_Server {
*
* @since 5.5.0
*
* @param string[] $allow_headers The list of headers to allow.
* @param string[] $allow_headers The list of request headers to allow.
*/
$allow_headers = apply_filters( 'rest_allowed_cors_headers', $allow_headers );
$this->send_header( 'Access-Control-Allow-Headers', implode( ', ', $allow_headers ) );
/**
* Send nocache headers on authenticated requests.
* Filters whether to send nocache headers on a REST API request.
*
* @since 4.4.0
*
@ -384,11 +384,11 @@ class WP_REST_Server {
);
/**
* Filters whether jsonp is enabled.
* Filters whether JSONP is enabled for the REST API.
*
* @since 4.4.0
*
* @param bool $jsonp_enabled Whether jsonp is enabled. Default true.
* @param bool $jsonp_enabled Whether JSONP is enabled. Default true.
*/
$jsonp_enabled = apply_filters( 'rest_jsonp_enabled', true );
@ -768,11 +768,17 @@ class WP_REST_Server {
);
/**
* Filters the enveloped form of a response.
* Filters the enveloped form of a REST API response.
*
* @since 4.4.0
*
* @param array $envelope Envelope data.
* @param array $envelope {
* Envelope data.
*
* @type array $body Response data.
* @type int $status The 3-digit HTTP status code.
* @type array $headers Map of header name to header value.
* }
* @param WP_REST_Response $response Original response data.
*/
$envelope = apply_filters( 'rest_envelope_response', $envelope, $response );
@ -857,7 +863,7 @@ class WP_REST_Server {
}
/**
* Filters the array of available endpoints.
* Filters the array of available REST API endpoints.
*
* @since 4.4.0
*
@ -957,7 +963,7 @@ class WP_REST_Server {
*/
public function dispatch( $request ) {
/**
* Filters the pre-calculated result of a REST dispatch request.
* Filters the pre-calculated result of a REST API dispatch request.
*
* Allow hijacking the request before dispatching by returning a non-empty. The returned value
* will be used to serve the request instead.
@ -1116,7 +1122,8 @@ class WP_REST_Server {
*
* @since 4.7.0
*
* @param WP_REST_Response|WP_HTTP_Response|WP_Error|mixed $response Result to send to the client. Usually a WP_REST_Response or WP_Error.
* @param WP_REST_Response|WP_HTTP_Response|WP_Error|mixed $response Result to send to the client.
* Usually a WP_REST_Response or WP_Error.
* @param array $handler Route handler used for the request.
* @param WP_REST_Request $request Request used to generate the response.
*/
@ -1139,7 +1146,7 @@ class WP_REST_Server {
if ( ! is_wp_error( $response ) ) {
/**
* Filters the REST dispatch request result.
* Filters the REST API dispatch request result.
*
* Allow plugins to override dispatching the request.
*
@ -1177,7 +1184,8 @@ class WP_REST_Server {
*
* @since 4.7.0
*
* @param WP_REST_Response|WP_HTTP_Response|WP_Error|mixed $response Result to send to the client. Usually a WP_REST_Response or WP_Error.
* @param WP_REST_Response|WP_HTTP_Response|WP_Error|mixed $response Result to send to the client.
* Usually a WP_REST_Response or WP_Error.
* @param array $handler Route handler used for the request.
* @param WP_REST_Request $request Request used to generate the response.
*/
@ -1323,7 +1331,7 @@ class WP_REST_Server {
$response->add_link( 'up', rest_url( '/' ) );
/**
* Filters the namespace index data.
* Filters the REST API namespace index data.
*
* This typically is just the route data for the namespace, but you can
* add any data you'd like here.
@ -1356,7 +1364,7 @@ class WP_REST_Server {
}
/**
* Filters the REST endpoint data.
* Filters the REST API endpoint data.
*
* @since 4.4.0
*
@ -1366,7 +1374,7 @@ class WP_REST_Server {
}
/**
* Filters the publicly-visible data for routes.
* Filters the publicly-visible data for REST API routes.
*
* This data is exposed on indexes and can be used by clients or
* developers to investigate the site and find out how to use it. It
@ -1466,7 +1474,7 @@ class WP_REST_Server {
*/
protected function get_max_batch_size() {
/**
* Filters the maximum number of requests that can be included in a batch.
* Filters the maximum number of REST API requests that can be included in a batch.
*
* @since 5.6.0
*

2
wp-includes/rest-api/endpoints/class-wp-rest-block-directory-controller.php
View File

@ -313,7 +313,7 @@ class WP_REST_Block_Directory_Controller extends WP_REST_Controller {
unset( $query_params['search'] );
/**
* Filters collection parameters for the block directory controller.
* Filters REST API collection parameters for the block directory controller.
*
* @since 5.5.0
*

14
wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php
View File

@ -449,7 +449,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
}
/**
* Filters whether comments can be created without authentication.
* Filters whether comments can be created via the REST API without authentication.
*
* Enables creating comments for anonymous users.
*
@ -955,14 +955,14 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
$force = isset( $request['force'] ) ? (bool) $request['force'] : false;
/**
* Filters whether a comment can be trashed.
* Filters whether a comment can be trashed via the REST API.
*
* Return false to disable Trash support for the post.
* Return false to disable trash support for the comment.
*
* @since 4.7.0
*
* @param bool $supports_trash Whether the post type support trashing.
* @param WP_Post $comment The comment object being considered for trashing support.
* @param bool $supports_trash Whether the comment supports trashing.
* @param WP_Comment $comment The comment object being considered for trashing support.
*/
$supports_trash = apply_filters( 'rest_comment_trashable', ( EMPTY_TRASH_DAYS > 0 ), $comment );
@ -1351,7 +1351,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
}
/**
* Filters a comment after it is prepared for the database.
* Filters a comment added via the REST API after it is prepared for insertion into the database.
*
* Allows modification of the comment right after it is prepared for the database.
*
@ -1674,7 +1674,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
);
/**
* Filters collection parameters for the comments controller.
* Filters REST API collection parameters for the comments controller.
*
* This filter registers the collection parameter, but does not map the
* collection parameter to an internal WP_Comment_Query parameter. Use the

2
wp-includes/rest-api/endpoints/class-wp-rest-plugins-controller.php
View File

@ -586,7 +586,7 @@ class WP_REST_Plugins_Controller extends WP_REST_Controller {
$response->add_links( $this->prepare_links( $item ) );
/**
* Filters the plugin data for a response.
* Filters plugin data for a REST API response.
*
* @since 5.5.0
*

4
wp-includes/rest-api/endpoints/class-wp-rest-post-statuses-controller.php
View File

@ -268,14 +268,14 @@ class WP_REST_Post_Statuses_Controller extends WP_REST_Controller {
}
/**
* Filters a status returned from the REST API.
* Filters a post status returned from the REST API.
*
* Allows modification of the status data right before it is returned.
*
* @since 4.7.0
*
* @param WP_REST_Response $response The response object.
* @param object $status The original status object.
* @param object $status The original post status object.
* @param WP_REST_Request $request Request used to generate the response.
*/
return apply_filters( 'rest_prepare_status', $response, $status, $request );

2
wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php
View File

@ -154,7 +154,7 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
}
/**
* Filters whether to preempt a setting value update.
* Filters whether to preempt a setting value update via the REST API.
*
* Allows hijacking the setting update logic and overriding the built-in behavior by
* returning true.

2
wp-includes/rest-api/endpoints/class-wp-rest-themes-controller.php
View File

@ -580,7 +580,7 @@ class WP_REST_Themes_Controller extends WP_REST_Controller {
);
/**
* Filters collection parameters for the themes controller.
* Filters REST API collection parameters for the themes controller.
*
* @since 5.0.0
*

2
wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php
View File

@ -1559,7 +1559,7 @@ class WP_REST_Users_Controller extends WP_REST_Controller {
);
/**
* Filters collection parameters for the users controller.
* Filters REST API collection parameters for the users controller.
*
* This filter registers the collection parameter, but does not map the
* collection parameter to an internal WP_User_Query parameter. Use the

2
wp-includes/rest-api/search/class-wp-rest-post-format-search-handler.php
View File

@ -46,7 +46,7 @@ class WP_REST_Post_Format_Search_Handler extends WP_REST_Search_Handler {
}
/**
* Filters the query arguments for a search request.
* Filters the query arguments for a REST API search request.
*
* Enables adding extra arguments or setting defaults for a post format search request.
*

2
wp-includes/rest-api/search/class-wp-rest-post-search-handler.php
View File

@ -71,7 +71,7 @@ class WP_REST_Post_Search_Handler extends WP_REST_Search_Handler {
}
/**
* Filters the query arguments for a search request.
* Filters the query arguments for a REST API search request.
*
* Enables adding extra arguments or setting defaults for a post search request.
*

2
wp-includes/rest-api/search/class-wp-rest-term-search-handler.php
View File

@ -66,7 +66,7 @@ class WP_REST_Term_Search_Handler extends WP_REST_Search_Handler {
}
/**
* Filters the query arguments for a search request.
* Filters the query arguments for a REST API search request.
*
* Enables adding extra arguments or setting defaults for a term search request.
*

2
wp-includes/version.php
View File

@ -13,7 +13,7 @@
*
* @global string $wp_version
*/
$wp_version = '5.7-alpha-49954';
$wp_version = '5.7-alpha-49955';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.