WordPress.org
Get WordPress

Make WordPress Core

Ticket #38398: 38398.patch

File 38398.patch, 9.4 KB (added by Soean, 7 years ago)

Docs: Improve documentation for WP_REST_Users_Controller.

  • src/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/**
    411 * Access users
    … …  
    815        /**
    916         * Instance of a user meta fields object.
    1017         *
     18         * @since 4.7.0
    1119         * @access protected
    1220         * @var WP_REST_User_Meta_Fields
    1321         */
    1422        protected $meta;
    1523
     24        /**
     25         * Constructor.
     26         *
     27         * @since 4.7.0
     28         */
    1629        public function __construct() {
    1730                $this->namespace = 'wp/v2';
    1831                $this->rest_base = 'users';
    … …  
    2134        }
    2235
    2336        /**
    24          * Register the routes for the objects of the controller.
     37         * Registers the routes for the objects of the controller.
     38         *
     39         * @since 4.7.0
    2540         */
    2641        public function register_routes() {
    2742
    … …  
    8398        /**
    8499         * Permissions check for getting all users.
    85100         *
     101         * @since 4.7.0
     102         *
    86103         * @param WP_REST_Request $request Full details about the request.
    87104         * @return WP_Error|boolean
    88105         */
    … …  
    104121        }
    105122
    106123        /**
    107          * Get all users
     124         * Gets all users
    108125         *
     126         * @since 4.7.0
     127         *
    109128         * @param WP_REST_Request $request Full details about the request.
    110129         * @return WP_Error|WP_REST_Response
    111130         */
    … …  
    170189                }
    171190
    172191                /**
    173                  * Filter arguments, before passing to WP_User_Query, when querying users via the REST API.
     192                 * Filters arguments, before passing to WP_User_Query, when querying users via the REST API.
    174193                 *
     194                 * @since 4.7.0
     195                 *
    175196                 * @see https://developer.wordpress.org/reference/classes/wp_user_query/
    176197                 *
    177198                 * @param array           $prepared_args Array of arguments for WP_User_Query.
    … …  
    197218
    198219                $total_users = $query->get_total();
    199220                if ( $total_users < 1 ) {
    200                         // Out-of-bounds, run the query again without LIMIT for total count
     221                        // Out-of-bounds, run the query again without LIMIT for total count.
    201222                        unset( $prepared_args['number'], $prepared_args['offset'] );
    202223                        $count_query = new WP_User_Query( $prepared_args );
    203224                        $total_users = $count_query->get_total();
    … …  
    225246        }
    226247
    227248        /**
    228          * Check if a given request has access to read a user
     249         * Checks if a given request has access to read a user
    229250         *
     251         * @since 4.7.0
     252         *
    230253         * @param  WP_REST_Request $request Full details about the request.
    231254         * @return WP_Error|boolean
    232255         */
    … …  
    254277        }
    255278
    256279        /**
    257          * Get a single user
     280         * Gets a single user
    258281         *
     282         * @since 4.7.0
     283         *
    259284         * @param WP_REST_Request $request Full details about the request.
    260285         * @return WP_Error|WP_REST_Response
    261286         */
    … …  
    274299        }
    275300
    276301        /**
    277          * Get the current user
     302         * Gets the current user
    278303         *
     304         * @since 4.7.0
     305         *
    279306         * @param WP_REST_Request $request Full details about the request.
    280307         * @return WP_Error|WP_REST_Response
    281308         */
    … …  
    295322        }
    296323
    297324        /**
    298          * Check if a given request has access create users
     325         * Checks if a given request has access create users
    299326         *
     327         * @since 4.7.0
     328         *
    300329         * @param  WP_REST_Request $request Full details about the request.
    301330         * @return WP_Error|boolean
    302331         */
    … …  
    310339        }
    311340
    312341        /**
    313          * Create a single user
     342         * Creates a single user
    314343         *
     344         * @since 4.7.0
     345         *
    315346         * @param WP_REST_Request $request Full details about the request.
    316347         * @return WP_Error|WP_REST_Response
    317348         */
    … …  
    375406                /**
    376407                 * Fires after a user is created or updated via the REST API.
    377408                 *
     409                 * @since 4.7.0
     410                 *
    378411                 * @param WP_User         $user      Data used to create the user.
    379412                 * @param WP_REST_Request $request   Request object.
    380413                 * @param boolean         $creating  True when creating user, false when updating user.
    … …  
    391424        }
    392425
    393426        /**
    394          * Check if a given request has access update a user
     427         * Checks if a given request has access update a user
    395428         *
     429         * @since 4.7.0
     430         *
    396431         * @param  WP_REST_Request $request Full details about the request.
    397432         * @return WP_Error|boolean
    398433         */
    … …  
    412447        }
    413448
    414449        /**
    415          * Update a single user
     450         * Updates a single user
    416451         *
     452         * @since 4.7.0
     453         *
    417454         * @param WP_REST_Request $request Full details about the request.
    418455         * @return WP_Error|WP_REST_Response
    419456         */
    … …  
    446483
    447484                $user = $this->prepare_item_for_database( $request );
    448485
    449                 // Ensure we're operating on the same user we already checked
     486                // Ensure we're operating on the same user we already checked.
    450487                $user->ID = $id;
    451488
    452489                $user_id = wp_update_user( $user );
    … …  
    482519        }
    483520
    484521        /**
    485          * Check if a given request has access delete a user
     522         * Checks if a given request has access delete a user
    486523         *
     524         * @since 4.7.0
     525         *
    487526         * @param  WP_REST_Request $request Full details about the request.
    488527         * @return WP_Error|boolean
    489528         */
    … …  
    499538        }
    500539
    501540        /**
    502          * Delete a single user
     541         * Deletes a single user
    503542         *
     543         * @since 4.7.0
     544         *
    504545         * @param WP_REST_Request $request Full details about the request.
    505546         * @return WP_Error|WP_REST_Response
    506547         */
    … …  
    509550                $reassign = isset( $request['reassign'] ) ? absint( $request['reassign'] ) : null;
    510551                $force = isset( $request['force'] ) ? (bool) $request['force'] : false;
    511552
    512                 // We don't support trashing for this type, error out
     553                // We don't support trashing for this type, error out.
    513554                if ( ! $force ) {
    514555                        return new WP_Error( 'rest_trash_not_supported', __( 'Users do not support trashing.' ), array( 'status' => 501 ) );
    515556                }
    … …  
    540581                /**
    541582                 * Fires after a user is deleted via the REST API.
    542583                 *
     584                 * @since 4.7.0
     585                 *
    543586                 * @param WP_User          $user     The user data.
    544587                 * @param WP_REST_Response $response The response returned from the API.
    545588                 * @param WP_REST_Request  $request  The request sent to the API.
    … …  
    550593        }
    551594
    552595        /**
    553          * Prepare a single user output for response
     596         * Prepares a single user output for response
    554597         *
    555          * @param object $user User object.
     598         * @since 4.7.0
     599         *
     600         * @param object          $user    User object.
    556601         * @param WP_REST_Request $request Request object.
    557602         * @return WP_REST_Response $response Response data.
    558603         */
    … …  
    634679                $data = $this->add_additional_fields_to_object( $data, $request );
    635680                $data = $this->filter_response_by_context( $data, $context );
    636681
    637                 // Wrap the data in a response object
     682                // Wrap the data in a response object.
    638683                $response = rest_ensure_response( $data );
    639684
    640685                $response->add_links( $this->prepare_links( $user ) );
    641686
    642687                /**
    643                  * Filter user data returned from the REST API.
     688                 * Filters user data returned from the REST API.
    644689                 *
     690                 * @since 4.7.0
     691                 *
    645692                 * @param WP_REST_Response $response  The response object.
    646693                 * @param object           $user      User object used to create response.
    647694                 * @param WP_REST_Request  $request   Request object.
    … …  
    650697        }
    651698
    652699        /**
    653          * Prepare links for the request.
     700         * Prepares links for the request.
    654701         *
     702         * @since 4.7.0
     703         *
    655704         * @param WP_Post $user User object.
    656705         * @return array Links for the given user.
    657706         */
    … …  
    669718        }
    670719
    671720        /**
    672          * Prepare a single user for create or update
     721         * Prepares a single user for create or update
    673722         *
     723         * @since 4.7.0
     724         *
    674725         * @param WP_REST_Request $request Request object.
    675726         * @return object $prepared_user User object.
    676727         */
    … …  
    723774                }
    724775
    725776                /**
    726                  * Filter user data before inserting user via the REST API.
     777                 * Filters user data before inserting user via the REST API.
    727778                 *
     779                 * @since 4.7.0
     780                 *
    728781                 * @param object          $prepared_user User object.
    729782                 * @param WP_REST_Request $request       Request object.
    730783                 */
    … …  
    732785        }
    733786
    734787        /**
    735          * Determine if the current user is allowed to make the desired roles change.
     788         * Determines if the current user is allowed to make the desired roles change.
    736789         *
     790         * @since 4.7.0
     791         *
    737792         * @param integer $user_id User ID.
    738793         * @param array   $roles   New user roles.
    739794         * @return WP_Error|boolean
    … …  
    754809                                return new WP_Error( 'rest_user_invalid_role', __( 'You cannot give resource that role.' ), array( 'status' => rest_authorization_required_code() ) );
    755810                        }
    756811
    757                         // The new role must be editable by the logged-in user.
    758 
    759812                        /** Include admin functions to get access to get_editable_roles() */
    760813                        require_once ABSPATH . 'wp-admin/includes/admin.php';
    761814
     815                        // The new role must be editable by the logged-in user.
    762816                        $editable_roles = get_editable_roles();
    763817                        if ( empty( $editable_roles[ $role ] ) ) {
    764818                                return new WP_Error( 'rest_user_invalid_role', __( 'You cannot give resource that role.' ), array( 'status' => 403 ) );
    … …  
    766820                }
    767821
    768822                return true;
    769 
    770823        }
    771824
    772825        /**
    773          * Get the User's schema, conforming to JSON Schema
     826         * Gets the User's schema, conforming to JSON Schema
    774827         *
     828         * @since 4.7.0
     829         *
    775830         * @return array
    776831         */
    777832        public function get_item_schema() {
    … …  
    878933                                'password'        => array(
    879934                                        'description' => __( 'Password for the resource (never included).' ),
    880935                                        'type'        => 'string',
    881                                         'context'     => array(), // Password is never displayed
     936                                        'context'     => array(), // Password is never displayed.
    882937                                        'required'    => true,
    883938                                ),
    884939                                'capabilities'    => array(
    … …  
    924979        }
    925980
    926981        /**
    927          * Get the query params for collections
     982         * Gets the query params for collections
    928983         *
     984         * @since 4.7.0
     985         *
    929986         * @return array
    930987         */
    931988        public function get_collection_params() {