From d3e10335d71b49fe3fea46524cc6fb8925d539f6 Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Sun, 30 Oct 2016 16:50:15 +0000 Subject: [PATCH] Docs: Add much more complete and syntactically correct documentation throughout the `WP_REST_Post_Types_Controller` class. Props Soean, mrahmadawais, flixos90. See #38398. git-svn-id: https://develop.svn.wordpress.org/trunk@39025 602fd350-edb4-49c9-b593-d223f7449a82 --- .../class-wp-rest-post-types-controller.php | 130 +++++++++++++----- 1 file changed, 93 insertions(+), 37 deletions(-) diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-post-types-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-post-types-controller.php index 293bf6b120..6f2aeee670 100644 --- a/src/wp-includes/rest-api/endpoints/class-wp-rest-post-types-controller.php +++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-post-types-controller.php @@ -1,44 +1,72 @@ namespace = 'wp/v2'; $this->rest_base = 'types'; } /** - * Register the routes for the objects of the controller. + * Registers the routes for the objects of the controller. + * + * @since 4.7.0 + * @access public + * + * @see register_rest_route() */ public function register_routes() { register_rest_route( $this->namespace, '/' . $this->rest_base, array( array( - 'methods' => WP_REST_Server::READABLE, - 'callback' => array( $this, 'get_items' ), + 'methods' => WP_REST_Server::READABLE, + 'callback' => array( $this, 'get_items' ), 'permission_callback' => array( $this, 'get_items_permissions_check' ), - 'args' => $this->get_collection_params(), + 'args' => $this->get_collection_params(), ), - 'schema' => array( $this, 'get_public_item_schema' ), + 'schema' => array( $this, 'get_public_item_schema' ), ) ); register_rest_route( $this->namespace, '/' . $this->rest_base . '/(?P[\w-]+)', array( array( - 'methods' => WP_REST_Server::READABLE, - 'callback' => array( $this, 'get_item' ), - 'args' => array( - 'context' => $this->get_context_param( array( 'default' => 'view' ) ), + 'methods' => WP_REST_Server::READABLE, + 'callback' => array( $this, 'get_item' ), + 'args' => array( + 'context' => $this->get_context_param( array( 'default' => 'view' ) ), ), ), - 'schema' => array( $this, 'get_public_item_schema' ), + 'schema' => array( $this, 'get_public_item_schema' ), ) ); } /** - * Check whether a given request has permission to read types. + * Checks whether a given request has permission to read types. * - * @param WP_REST_Request $request Full details about the request. - * @return WP_Error|boolean + * @since 4.7.0 + * @access public + * + * @param WP_REST_Request $request Full details about the request. + * @return WP_Error|true True if the request has read access, WP_Error object otherwise. */ public function get_items_permissions_check( $request ) { if ( 'edit' === $request['context'] ) { @@ -47,56 +75,75 @@ class WP_REST_Post_Types_Controller extends WP_REST_Controller { return true; } } + return new WP_Error( 'rest_cannot_view', __( 'Sorry, you cannot view this resource with edit context.' ), array( 'status' => rest_authorization_required_code() ) ); } + return true; } /** - * Get all public post types + * Retrieves all public post types. * - * @param WP_REST_Request $request - * @return array|WP_Error + * @since 4.7.0 + * @access public + * + * @param WP_REST_Request $request Full details about the request. + * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure. */ public function get_items( $request ) { $data = array(); + foreach ( get_post_types( array(), 'object' ) as $obj ) { if ( empty( $obj->show_in_rest ) || ( 'edit' === $request['context'] && ! current_user_can( $obj->cap->edit_posts ) ) ) { continue; } + $post_type = $this->prepare_item_for_response( $obj, $request ); $data[ $obj->name ] = $this->prepare_response_for_collection( $post_type ); } + return rest_ensure_response( $data ); } /** - * Get a specific post type + * Retrieves a specific post type. * - * @param WP_REST_Request $request - * @return array|WP_Error + * @since 4.7.0 + * @access public + * + * @param WP_REST_Request $request Full details about the request. + * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure. */ public function get_item( $request ) { $obj = get_post_type_object( $request['type'] ); + if ( empty( $obj ) ) { return new WP_Error( 'rest_type_invalid', __( 'Invalid resource.' ), array( 'status' => 404 ) ); } + if ( empty( $obj->show_in_rest ) ) { return new WP_Error( 'rest_cannot_read_type', __( 'Cannot view resource.' ), array( 'status' => rest_authorization_required_code() ) ); } + if ( 'edit' === $request['context'] && ! current_user_can( $obj->cap->edit_posts ) ) { return new WP_Error( 'rest_forbidden_context', __( 'Sorry, you are not allowed to manage this resource.' ), array( 'status' => rest_authorization_required_code() ) ); } + $data = $this->prepare_item_for_response( $obj, $request ); + return rest_ensure_response( $data ); } /** - * Prepare a post type object for serialization + * Prepares a post type object for serialization. * - * @param stdClass $post_type Post type data - * @param WP_REST_Request $request - * @return WP_REST_Response $response + * @since 4.7.0 + * @access public + * + * @param stdClass $post_type Post type data. + * @param WP_REST_Request $request Full details about the request. + * @return WP_REST_Response Response object. */ public function prepare_item_for_response( $post_type, $request ) { $data = array( @@ -108,38 +155,44 @@ class WP_REST_Post_Types_Controller extends WP_REST_Controller { 'slug' => $post_type->name, ); $context = ! empty( $request['context'] ) ? $request['context'] : 'view'; - $data = $this->add_additional_fields_to_object( $data, $request ); - $data = $this->filter_response_by_context( $data, $context ); + $data = $this->add_additional_fields_to_object( $data, $request ); + $data = $this->filter_response_by_context( $data, $context ); // Wrap the data in a response object. $response = rest_ensure_response( $data ); $base = ! empty( $post_type->rest_base ) ? $post_type->rest_base : $post_type->name; + $response->add_links( array( - 'collection' => array( - 'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ), + 'collection' => array( + 'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ), ), 'https://api.w.org/items' => array( - 'href' => rest_url( sprintf( 'wp/v2/%s', $base ) ), + 'href' => rest_url( sprintf( 'wp/v2/%s', $base ) ), ), ) ); /** - * Filter a post type returned from the API. + * Filters a post type returned from the API. * * Allows modification of the post type data right before it is returned. * - * @param WP_REST_Response $response The response object. - * @param object $item The original post type object. - * @param WP_REST_Request $request Request used to generate the response. + * @since 4.7.0 + * + * @param WP_REST_Response $response The response object. + * @param object $item The original post type object. + * @param WP_REST_Request $request Request used to generate the response. */ return apply_filters( 'rest_prepare_post_type', $response, $post_type, $request ); } /** - * Get the Post type's schema, conforming to JSON Schema + * Retrieves the post type's schema, conforming to JSON Schema. * - * @return array + * @since 4.7.0 + * @access public + * + * @return array Item schema data. */ public function get_item_schema() { $schema = array( @@ -189,13 +242,16 @@ class WP_REST_Post_Types_Controller extends WP_REST_Controller { } /** - * Get the query params for collections + * Retrieves the query params for collections. * - * @return array + * @since 4.7.0 + * @access public + * + * @return array Collection parameters. */ public function get_collection_params() { return array( - 'context' => $this->get_context_param( array( 'default' => 'view' ) ), + 'context' => $this->get_context_param( array( 'default' => 'view' ) ), ); }