Index: src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php =================================================================== --- src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php (revision 38853) +++ src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php (working copy) @@ -1,4 +1,11 @@ namespace = 'wp/v2'; $this->rest_base = 'users'; @@ -21,7 +34,9 @@ } /** - * Register the routes for the objects of the controller. + * Registers the routes for the objects of the controller. + * + * @since 4.7.0 */ public function register_routes() { @@ -83,6 +98,8 @@ /** * Permissions check for getting all users. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -104,8 +121,10 @@ } /** - * Get all users + * Gets all users * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -170,8 +189,10 @@ } /** - * Filter arguments, before passing to WP_User_Query, when querying users via the REST API. + * Filters arguments, before passing to WP_User_Query, when querying users via the REST API. * + * @since 4.7.0 + * * @see https://developer.wordpress.org/reference/classes/wp_user_query/ * * @param array $prepared_args Array of arguments for WP_User_Query. @@ -197,7 +218,7 @@ $total_users = $query->get_total(); if ( $total_users < 1 ) { - // Out-of-bounds, run the query again without LIMIT for total count + // Out-of-bounds, run the query again without LIMIT for total count. unset( $prepared_args['number'], $prepared_args['offset'] ); $count_query = new WP_User_Query( $prepared_args ); $total_users = $count_query->get_total(); @@ -225,8 +246,10 @@ } /** - * Check if a given request has access to read a user + * Checks if a given request has access to read a user * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -254,8 +277,10 @@ } /** - * Get a single user + * Gets a single user * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -274,8 +299,10 @@ } /** - * Get the current user + * Gets the current user * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -295,8 +322,10 @@ } /** - * Check if a given request has access create users + * Checks if a given request has access create users * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -310,8 +339,10 @@ } /** - * Create a single user + * Creates a single user * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -375,6 +406,8 @@ /** * Fires after a user is created or updated via the REST API. * + * @since 4.7.0 + * * @param WP_User $user Data used to create the user. * @param WP_REST_Request $request Request object. * @param boolean $creating True when creating user, false when updating user. @@ -391,8 +424,10 @@ } /** - * Check if a given request has access update a user + * Checks if a given request has access update a user * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -412,8 +447,10 @@ } /** - * Update a single user + * Updates a single user * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -446,7 +483,7 @@ $user = $this->prepare_item_for_database( $request ); - // Ensure we're operating on the same user we already checked + // Ensure we're operating on the same user we already checked. $user->ID = $id; $user_id = wp_update_user( $user ); @@ -482,8 +519,10 @@ } /** - * Check if a given request has access delete a user + * Checks if a given request has access delete a user * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -499,8 +538,10 @@ } /** - * Delete a single user + * Deletes a single user * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -509,7 +550,7 @@ $reassign = isset( $request['reassign'] ) ? absint( $request['reassign'] ) : null; $force = isset( $request['force'] ) ? (bool) $request['force'] : false; - // We don't support trashing for this type, error out + // We don't support trashing for this type, error out. if ( ! $force ) { return new WP_Error( 'rest_trash_not_supported', __( 'Users do not support trashing.' ), array( 'status' => 501 ) ); } @@ -540,6 +581,8 @@ /** * Fires after a user is deleted via the REST API. * + * @since 4.7.0 + * * @param WP_User $user The user data. * @param WP_REST_Response $response The response returned from the API. * @param WP_REST_Request $request The request sent to the API. @@ -550,9 +593,11 @@ } /** - * Prepare a single user output for response + * Prepares a single user output for response * - * @param object $user User object. + * @since 4.7.0 + * + * @param object $user User object. * @param WP_REST_Request $request Request object. * @return WP_REST_Response $response Response data. */ @@ -634,14 +679,16 @@ $data = $this->add_additional_fields_to_object( $data, $request ); $data = $this->filter_response_by_context( $data, $context ); - // Wrap the data in a response object + // Wrap the data in a response object. $response = rest_ensure_response( $data ); $response->add_links( $this->prepare_links( $user ) ); /** - * Filter user data returned from the REST API. + * Filters user data returned from the REST API. * + * @since 4.7.0 + * * @param WP_REST_Response $response The response object. * @param object $user User object used to create response. * @param WP_REST_Request $request Request object. @@ -650,8 +697,10 @@ } /** - * Prepare links for the request. + * Prepares links for the request. * + * @since 4.7.0 + * * @param WP_Post $user User object. * @return array Links for the given user. */ @@ -669,8 +718,10 @@ } /** - * Prepare a single user for create or update + * Prepares a single user for create or update * + * @since 4.7.0 + * * @param WP_REST_Request $request Request object. * @return object $prepared_user User object. */ @@ -723,8 +774,10 @@ } /** - * Filter user data before inserting user via the REST API. + * Filters user data before inserting user via the REST API. * + * @since 4.7.0 + * * @param object $prepared_user User object. * @param WP_REST_Request $request Request object. */ @@ -732,8 +785,10 @@ } /** - * Determine if the current user is allowed to make the desired roles change. + * Determines if the current user is allowed to make the desired roles change. * + * @since 4.7.0 + * * @param integer $user_id User ID. * @param array $roles New user roles. * @return WP_Error|boolean @@ -754,11 +809,10 @@ return new WP_Error( 'rest_user_invalid_role', __( 'You cannot give resource that role.' ), array( 'status' => rest_authorization_required_code() ) ); } - // The new role must be editable by the logged-in user. - /** Include admin functions to get access to get_editable_roles() */ require_once ABSPATH . 'wp-admin/includes/admin.php'; + // The new role must be editable by the logged-in user. $editable_roles = get_editable_roles(); if ( empty( $editable_roles[ $role ] ) ) { return new WP_Error( 'rest_user_invalid_role', __( 'You cannot give resource that role.' ), array( 'status' => 403 ) ); @@ -766,12 +820,13 @@ } return true; - } /** - * Get the User's schema, conforming to JSON Schema + * Gets the User's schema, conforming to JSON Schema * + * @since 4.7.0 + * * @return array */ public function get_item_schema() { @@ -878,7 +933,7 @@ 'password' => array( 'description' => __( 'Password for the resource (never included).' ), 'type' => 'string', - 'context' => array(), // Password is never displayed + 'context' => array(), // Password is never displayed. 'required' => true, ), 'capabilities' => array( @@ -924,8 +979,10 @@ } /** - * Get the query params for collections + * Gets the query params for collections * + * @since 4.7.0 + * * @return array */ public function get_collection_params() {